There are three ways to authenticate the Ocuroot CLI to a server:
  1. Browser Login (Recommended for developers) 
    ocuroot auth login
    This opens your browser to complete authentication and stores the token in ~/.ocuroot/auth. Use this when:
    • You’re working on your development machine
    • You want to use your personal account credentials
    • You need access to all resources you have permission for
  2. Repository-Specific Login (recommended for testing) 
    ocuroot auth login --local
    Similar to browser login, but stores the token in .ocuroot/auth within your repository. Use this when:
    • Different repositories need different access levels
    • You’re collaborating on a project and want to keep auth separate
    • You want to use different accounts for different repositories
  3. Environment Variable (recommended for CI and other automation) 
    export OCUROOT_API_KEY=your_token_here
    Set the OCUROOT_API_KEY environment variable with your token. Use this when:
    • Setting up CI/CD pipelines
    • Running in automated environments
    • You need to temporarily override stored credentials

​
Common Scenarios

​
Local Development

For most development work, use browser login with global storage: 
ocuroot auth login

​
Multiple Projects

If you work on multiple projects with different access levels:
  1. Navigate to each project directory
  2. Run ocuroot auth login --local
  3. Use different accounts as needed

​
CI/CD Setup

For automated environments:
  1. Create a service account via the Ocuroot web UI
  2. Get an API key for the service account
  3. Set it as OCUROOT_API_KEY in your CI environment variables

​
Temporary Override

To quickly test with different credentials: 
OCUROOT_API_KEY=your_token_here ocuroot <command>
This overrides stored credentials for just one command.

​
Managing Your Authentication

Check your current auth status: 
ocuroot auth view
Remove stored credentials: 
ocuroot auth logout        # Remove global credentials
ocuroot auth logout --local # Remove repository-specific credentials

​
Best Practices

  • Use browser login for day-to-day development
  • Set up repository-specific auth when working on multiple projects
  • Use environment variables for CI/CD and automation
  • Never commit .ocuroot/auth files to version control
  • Use service accounts with minimal permissions for automated tasks