Skip to content

✨ Add CLI authentication with OAuth device flow #56

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Robdel12 merged 2 commits into from
Oct 16, 2025
Merged

✨ Add CLI authentication with OAuth device flow #56

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f6c11c2
✨ Add CLI authentication with OAuth device flow
Robdel12 Oct 16, 2025
c8b8c6f
🔒 Fix command injection vulnerability in browser utility
Robdel12 Oct 16, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
119 changes: 115 additions & 4 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,16 +36,44 @@ npm install -g @vizzly-testing/cli
vizzly init
```

### Set up your API token
### Authentication

For local development, create a `.env` file in your project root and add your token:
Vizzly supports two authentication methods:

**Option 1: User Authentication (Recommended for local development)**
```bash
# Authenticate with your Vizzly account
vizzly login

# Optional: Configure project-specific token
vizzly project:select

# Run tests
vizzly run "npm test"
```

**Option 2: API Token (Recommended for CI/CD)**
```bash
# Set via environment variable
export VIZZLY_TOKEN=your-project-token

# Run tests
vizzly run "npm test"
```

For local development with `.env` files:
```
VIZZLY_TOKEN=your-api-token
VIZZLY_TOKEN=your-project-token
```

Then add `.env` to your `.gitignore` file. For CI/CD, use your provider's secret management system.

**Token Priority:**
1. CLI flag (`--token`)
2. Environment variable (`VIZZLY_TOKEN`)
3. Project mapping (configured via `vizzly project:select`)
4. User access token (from `vizzly login`)

### Upload existing screenshots

```bash
Expand Down Expand Up @@ -88,6 +116,84 @@ await vizzlyScreenshot('homepage', './screenshots/homepage.png', {

## Commands

### Authentication Commands

```bash
vizzly login # Authenticate with your Vizzly account
vizzly logout # Clear stored authentication tokens
vizzly whoami # Show current user and authentication status
vizzly project:select # Configure project-specific token
vizzly project:list # Show all configured projects
vizzly project:token # Display project token for current directory
vizzly project:remove # Remove project configuration
```

#### Login Command
Authenticate using OAuth 2.0 device flow. Opens your browser to authorize the CLI with your Vizzly account.

```bash
# Interactive browser-based login
vizzly login

# JSON output for scripting
vizzly login --json
```

**Features:**
- Browser auto-opens with pre-filled device code
- Secure OAuth 2.0 device authorization flow
- 30-day token expiry with automatic refresh
- Tokens stored securely in `~/.vizzly/config.json` with 0600 permissions

#### Logout Command
Clear all stored authentication tokens from your machine.

```bash
# Clear all tokens
vizzly logout

# JSON output
vizzly logout --json
```

Revokes tokens on the server and removes them from local storage.

#### Whoami Command
Display current authentication status, user information, and organizations.

```bash
# Show user and authentication info
vizzly whoami

# JSON output for scripting
vizzly whoami --json
```

Shows:
- Current user email and name
- Organizations you belong to
- Token status and expiry
- Project mappings (if any)

#### Project Commands
Configure directory-specific project tokens for multi-project workflows.

```bash
# Select a project for current directory
vizzly project:select

# List all configured projects
vizzly project:list

# Show token for current directory
vizzly project:token

# Remove project configuration
vizzly project:remove
```

**Use case:** Working on multiple Vizzly projects? Configure each project directory with its specific token. The CLI automatically uses the right token based on your current directory.

### Upload Screenshots
```bash
vizzly upload <directory> # Upload screenshots from directory
Expand Down Expand Up @@ -471,6 +577,7 @@ See the [Plugin Development Guide](./docs/plugins.md) for complete documentation
## Documentation

- [Getting Started](./docs/getting-started.md)
- [Authentication Guide](./docs/authentication.md)
- [Upload Command Guide](./docs/upload-command.md)
- [Test Integration Guide](./docs/test-integration.md)
- [TDD Mode Guide](./docs/tdd-mode.md)
Expand All @@ -483,8 +590,12 @@ See the [Plugin Development Guide](./docs/plugins.md) for complete documentation

## Environment Variables

### Authentication
- `VIZZLY_TOKEN`: API authentication token (project token or access token). Example: `export VIZZLY_TOKEN=your-token`.
- For local development: Use `vizzly login` instead of manually managing tokens
- For CI/CD: Use project tokens from environment variables

### Core Configuration
- `VIZZLY_TOKEN`: API authentication token. Example: `export VIZZLY_TOKEN=your-token`.
- `VIZZLY_API_URL`: Override API base URL. Default: `https://app.vizzly.dev`.
- `VIZZLY_LOG_LEVEL`: Logger level. One of `debug`, `info`, `warn`, `error`. Example: `export VIZZLY_LOG_LEVEL=debug`.

Expand Down
120 changes: 118 additions & 2 deletions docs/api-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -326,6 +326,117 @@ vizzly.on('comparison:failed', (error) => {

## CLI Commands

### Authentication Commands

#### `vizzly login`

Authenticate using OAuth 2.0 device flow.

**Options:**
- `--json` - Machine-readable JSON output
- `--verbose` - Verbose output

**Exit Codes:**
- `0` - Login successful
- `1` - Login failed

**Example:**
```bash
vizzly login
```

#### `vizzly logout`

Clear stored authentication tokens.

**Options:**
- `--json` - Machine-readable JSON output
- `--verbose` - Verbose output

**Exit Codes:**
- `0` - Logout successful
- `1` - Logout failed

**Example:**
```bash
vizzly logout
```

#### `vizzly whoami`

Display current user and authentication status.

**Options:**
- `--json` - Machine-readable JSON output

**Exit Codes:**
- `0` - Success
- `1` - Not authenticated or error

**Example:**
```bash
vizzly whoami
```

#### `vizzly project:select`

Configure project-specific token for current directory.

**Options:**
- `--json` - Machine-readable JSON output

**Exit Codes:**
- `0` - Project configured successfully
- `1` - Configuration failed

**Example:**
```bash
cd /path/to/project
vizzly project:select
```

#### `vizzly project:list`

Show all configured projects.

**Exit Codes:**
- `0` - Success
- `1` - Error

**Example:**
```bash
vizzly project:list
```

#### `vizzly project:token`

Display project token for current directory.

**Options:**
- `--json` - Machine-readable JSON output

**Exit Codes:**
- `0` - Success
- `1` - No project configured or error

**Example:**
```bash
vizzly project:token
```

#### `vizzly project:remove`

Remove project configuration for current directory.

**Exit Codes:**
- `0` - Success
- `1` - No project configured or error

**Example:**
```bash
vizzly project:remove
```

### `vizzly upload <path>`

Upload screenshots from a directory.
Expand Down Expand Up @@ -557,9 +668,14 @@ Configuration loaded via cosmiconfig in this order:

### Environment Variables

**Authentication:**
- `VIZZLY_TOKEN` - API authentication token (project token or access token)
- For local development: Use `vizzly login` instead of manually managing tokens
- For CI/CD: Use project tokens from environment variables
- Token priority: CLI flag → env var → project mapping → user access token

**Core Configuration:**
- `VIZZLY_TOKEN` - API authentication token
- `VIZZLY_API_URL` - API base URL override
- `VIZZLY_API_URL` - API base URL override (default: `https://app.vizzly.dev`)
- `VIZZLY_LOG_LEVEL` - Logger level (`debug`, `info`, `warn`, `error`)

**Parallel Builds:**
Expand Down
Loading