Authentication

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