Authentication

The CLI needs to know who you are. You can log in as yourself for local development, or use project tokens for automation.

How It Works

Vizzly CLI supports two ways to authenticate:

OAuth Login - Best for local development. Log in once, work on any project. The CLI handles token refresh automatically.

Project Tokens - Best for CI/CD. Direct token authentication, no user session needed.

Logging In

vizzly login

This starts an OAuth device flow. Here’s what happens:

The CLI generates a device code
Your browser opens to https://app.vizzly.dev/auth/device with the code pre-filled
You authorize the CLI with your Vizzly account
Press Enter in the terminal
You’re in

The CLI stores your tokens in ~/.vizzly/config.json with secure permissions (owner read/write only). Tokens refresh automatically when they’re about to expire - you won’t even notice.

Get JSON output:

vizzly login --json

Checking Who You Are

vizzly whoami

Shows your current user, organizations, and token expiry. Useful for confirming you’re logged in correctly.

Example:

Authenticated

User: Jane Developer
Email: jane@example.com

Organizations:
  - Acme Inc (@acme)
  - Personal (@jane)

Token expires in 29 days (2025-12-15)

Get JSON output:

vizzly whoami --json

Logging Out

vizzly logout

Revokes your tokens on the server and clears them locally. Your project mappings (from vizzly project:select) stay intact.

Project-Specific Tokens

If you work on multiple projects, you can map specific tokens to directories. The CLI automatically uses the right token based on where you are.

Selecting a Project

cd /path/to/project
vizzly project:select

This walks you through:

Choose an organization
Choose a project
The CLI creates a new project token automatically and saves it for this directory

The token gets stored in ~/.vizzly/config.json mapped to your current directory path. The CLI walks up the directory tree to find the closest mapping, so subdirectories inherit the token.

Listing Project Mappings

vizzly project:list

Shows all configured projects:

Project mappings:
  /Users/jane/acme-app → Acme Inc / Marketing Site
  /Users/jane/personal → Personal / Landing Page

Showing the Current Token

vizzly project:token

Displays the first 10 characters of the project token for the current directory.

Get the full token:

vizzly project:token --json

Removing a Project

vizzly project:remove

Deletes the project mapping for the current directory.

Using Tokens Directly

For CI/CD or automated environments, skip OAuth and use project tokens directly.

Environment Variable

export VIZZLY_TOKEN=vzt_your_project_token_here
vizzly run "npm test"

CLI Flag

vizzly run "npm test" --token vzt_your_project_token_here

.env File (Local Only)

Create a .env file in your project root:

VIZZLY_TOKEN=vzt_your_project_token_here

Important: Add .env to .gitignore. Never commit tokens.

CI/CD Examples

Use your CI provider’s secret manager:

GitHub Actions:

- name: Run visual tests
  run: npx vizzly run "npm test" --wait
  env:
    VIZZLY_TOKEN: ${{ secrets.VIZZLY_TOKEN }}

GitLab CI:

visual-tests:
  script:
    - npx vizzly run "npm test" --wait
  variables:
    VIZZLY_TOKEN: $VIZZLY_TOKEN

CircleCI:

- run:
    name: Visual tests
    command: npx vizzly run "npm test" --wait
    environment:
      VIZZLY_TOKEN: $VIZZLY_TOKEN

Token Resolution

The CLI looks for tokens in this order:

--token flag (highest priority)
VIZZLY_TOKEN environment variable
Project mapping (from vizzly project:select)
User access token (from vizzly login)

This lets you override authentication for specific commands while keeping defaults for regular use.

Examples:

# Override with flag
vizzly run "npm test" --token vzt_different_token

# Use project mapping
cd /path/to/project
vizzly run "npm test"

# Fallback to user token
vizzly login
cd /new/project
vizzly run "npm test"

Advanced Configuration

Custom config location:

Set VIZZLY_HOME to change where the CLI stores authentication:

export VIZZLY_HOME=/custom/path
vizzly login

Useful for isolating dev and production configs, or running tests.

Troubleshooting

Authentication fails with “Invalid or expired API token”

If you’re using vizzly login, the token should refresh automatically. If it doesn’t:

vizzly logout
vizzly login

If you’re using VIZZLY_TOKEN or a project mapping, the token might be expired or invalid. Generate a new project token from the Vizzly dashboard.

Project token not being used

Check your project mappings:

vizzly project:list

The CLI walks up the directory tree to find mappings. If you’re in /Users/jane/project/src, it will look for mappings in:

/Users/jane/project/src
/Users/jane/project
/Users/jane
/Users

If nothing matches, it falls back to environment variables or user tokens.

”Not authenticated” error

You need to either:

vizzly login

Or set a token:

export VIZZLY_TOKEN=vzt_your_project_token

Security

Never commit tokens - Add .env to .gitignore
Use CI secrets - Store VIZZLY_TOKEN in your provider’s secret manager
Tokens auto-refresh - User tokens refresh transparently, no manual intervention needed
Secure storage - Local tokens are stored with 0o600 permissions (owner-only access)