Skip to Content

Authentication

TL;DR

CMDOP authenticates via OAuth 2.0 with cmdop login, which opens a browser for sign-in and stores credentials locally. For CI/CD and scripts, create API keys with cmdop auth create-key and set the CMDOP_API_KEY environment variable. Integrations are available for GitHub Actions, GitLab CI, and Jenkins. Keys support scoped permissions and expiration.

CMDOP uses OAuth 2.0 for secure authentication.

How do I log in?

# Opens browser for OAuth authentication
cmdop login

Opens browser for authentication. After success, credentials are stored locally.

✓ Authenticated as: [email protected]
✓ Workspace: acme-corp

How do I check my authentication status?

# Display current auth state, workspace, and token expiry
cmdop auth status

Output:

✓ Authenticated as: [email protected]
✓ Workspace: acme-corp
✓ Token expires: 2026-03-14

How do I log out?

# Remove stored credentials from this machine
cmdop logout

Removes local credentials.

How do I use API keys?

For servers and scripts, use API keys.

How do I create an API key?

# Create a named API key for automation
cmdop auth create-key --name "my-script"

Output:

API Key created: cmd_acme_a1b2c3d4e5f6...

⚠ Copy this key now. It won't be shown again.

How do I use an API key?

# Set API key as environment variable for the session
export CMDOP_API_KEY=cmd_acme_xxx
cmdop machines

Or inline:

# Pass API key for a single command invocation
CMDOP_API_KEY=cmd_acme_xxx cmdop exec server "uptime"

How do I list my API keys?

# Show all API keys with creation date and permissions
cmdop auth list-keys

How do I revoke an API key?

# Permanently invalidate an API key
cmdop auth revoke-key cmd_acme_xxx

Where are credentials stored?

PlatformLocation
macOS~/.cmdop/auth.json
Linux~/.cmdop/auth.json
Windows%APPDATA%\cmdop\auth.json

Permissions: 0600 (owner read/write only)

What environment variables are supported?

VariableDescription
CMDOP_API_KEYAPI key for authentication
CMDOP_SERVER_ADDRESSControl Plane address
CMDOP_WORKSPACEDefault workspace

How do I integrate with CI/CD?

How do I use CMDOP with GitHub Actions?

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Install CMDOP
        run: curl -sSL cmdop.com/install.sh | bash
 
      - name: Deploy
        env:
          CMDOP_API_KEY: ${{ secrets.CMDOP_API_KEY }}
        run: |
          cmdop exec prod-server "./deploy.sh"

How do I use CMDOP with GitLab CI?

deploy:
  script:
    - curl -sSL cmdop.com/install.sh | bash
    - cmdop exec prod-server "./deploy.sh"
  variables:
    CMDOP_API_KEY: $CMDOP_API_KEY

How do I use CMDOP with Jenkins?

pipeline {
    environment {
        CMDOP_API_KEY = credentials('cmdop-api-key')
    }
    stages {
        stage('Deploy') {
            steps {
                sh 'curl -sSL cmdop.com/install.sh | bash'
                sh 'cmdop exec prod-server "./deploy.sh"'
            }
        }
    }
}

What are the security best practices?

1. Use Separate Keys

Personal:  cmd_acme_alice_xxx
CI/CD:     cmd_acme_cicd_yyy
Prod:      cmd_acme_prod_zzz

2. Minimal Permissions

cmdop auth create-key --name "read-only" --permissions sessions:read

3. Rotate Keys

# Revoke old
cmdop auth revoke-key cmd_acme_old
 
# Create new
cmdop auth create-key --name "my-script"

4. Monitor Usage

# View audit trail of API key usage
cmdop audit list --action auth.api_key_used

How do I troubleshoot authentication issues?

Token Expired

cmdop logout
cmdop login

Invalid API Key

# Verify key
cmdop auth status
 
# Create new key if needed
cmdop auth create-key --name "new-key"

Permission Denied

# Check your permissions
cmdop auth status
 
# Check workspace membership
cmdop workspace current
Last updated on
Overview