Authentication

Some CoreViz CLI features require authentication to access cloud services. This guide explains how to authenticate and use cloud features.

Why Authenticate?

Authentication is required for:

• Cloud API features (enhanced search, embeddings)
• Accessing your CoreViz Studio datasets
• Using cloud-based AI processing
• Syncing with your CoreViz account

Many features work without authentication using local processing:

• Local image search (creates local index)
• Local tagging (offline mode)
• Local image description

Login

Authenticate with CoreViz using device authorization:

npx @coreviz/cli login

This will:

1. Open a browser window, or
2. Display a code and URL for manual authorization

Follow the on-screen instructions to complete authentication.

Device Authorization Flow

If a browser doesn't open automatically:

1. The CLI will display a code and URL
2. Visit the URL in your browser
3. Enter the code when prompted
4. Authorize the CLI to access your account

Check Authentication Status

Verify you're logged in:

npx @coreviz/cli whoami

This displays:

• Your authenticated email/username
• Account information
• Or indicates if you're not logged in

Logout

Sign out from your CoreViz account:

npx @coreviz/cli logout

This removes stored credentials and signs you out of all CLI sessions.

Using Cloud Features

Once authenticated, you can use cloud features by specifying the --mode api option:

# Use cloud API for search
npx @coreviz/cli search "query" --mode api

# Use cloud API for tagging
npx @coreviz/cli tag image.jpg "prompt" --mode api

Local vs Cloud Mode

Local Mode (No Authentication Required)

• Search: Creates local .index.db file, works offline
• Tagging: Uses local models, works offline
• Description: Uses local models, works offline

Advantages:

• Works offline
• No authentication needed
• Fast for local files
• Privacy-focused

Limitations:

• Requires local storage for index
• May have less accurate results
• Limited to local files

Cloud Mode (Authentication Required)

• Search: Uses cloud embeddings, more accurate
• Tagging: Uses cloud AI models, better accuracy
• Description: Uses cloud AI models, more detailed

Advantages:

• More accurate results
• Access to latest AI models
• Can search cloud datasets
• Better for large-scale operations

Limitations:

• Requires internet connection
• Requires authentication
• May have usage limits

Troubleshooting

Authentication Failed

If login fails:

1. Check your internet connection
2. Verify you can access lab.coreviz.io
3. Try logging out and logging back in
4. Check for firewall or proxy issues

Token Expired

If you get authentication errors:

npx @coreviz/cli logout
npx @coreviz/cli login

Permission Denied

If you see permission errors:

• Verify your account has access to the requested resources
• Check that you're using the correct account
• Contact support if issues persist

Security Notes

• Credentials are stored securely on your local machine
• Never share your authentication tokens
• Use logout on shared machines
• Credentials are stored in your home directory (platform-specific)

Next Steps

• Commands: Learn about all available CLI commands
• Installation: Review installation instructions