Authentication

OAuth, API keys, per-mode token storage, password gates, MFA, and how cmdop scopes credentials per workspace.

cmdop login opens a browser to the OAuth consent screen. After approval, the CLI receives a token, picks the active workspace from your account default, and writes ~/.cmdop/token_<mode>.json (mode 0600). On subsequent invocations, the token is auto-refreshed in the background — about 5 minutes before expiry — by the daemon’s token refresher goroutine.


cmdop login
cmdop auth status
cmdop logout

Example status:


$ cmdop auth status
Identity:    [email protected]
Workspace:   acme-prod
Mode:        prod
Token:       ~/.cmdop/token_prod.json
Expires:     2026-05-04T08:12:00Z

Per-mode token storage

cmdop has two scopes — prod and dev. Each has its own token file, its own active workspace, its own endpoint set:

Mode	Token file	Endpoint base
`prod`	`~/.cmdop/token_prod.json`	`api.cmdop.com`
`dev`	`~/.cmdop/token_dev.json`	`api-dev.cmdop.com`

Switching mode (cmdop mode toggle) does not re-prompt for OAuth if both tokens already exist. If only one exists, you will be prompted to log in for the other. See ./mode.

Tokens are workspace-scoped at issue time. Switching workspace via cmdop connect workspace use does not re-issue the token — the daemon migrates workspace context server-side and reconnects.

API keys for scripts and CI

For non-interactive use (CI, cron, scripts), generate an API key in the cabinet (Workspace → API Keys) or with cmdop connect key set. Pass via env var:


export CMDOP_API_KEY=cmd_acme_a1b2c3...
cmdop machines
 
# inline for one command
CMDOP_API_KEY=cmd_acme_a1b2c3... cmdop connect exec vps-audi -- uptime

API keys are workspace-scoped. To switch workspaces under an API key, use --workspace:


cmdop --workspace=acme-staging connect exec vps-audi -- whoami

Auth subtree


cmdop auth status              # current identity, workspace, expiry
cmdop auth login               # alias for cmdop login
cmdop auth logout              # alias for cmdop logout
cmdop auth password set        # set OAuth password (rarely needed; usually via web)
cmdop auth password clear
cmdop auth password status
cmdop auth password mfa        # enrol MFA / TOTP
cmdop auth password export     # export credentials (encrypted)

password mfa walks you through TOTP enrolment with QR code + backup codes. password export produces an encrypted bundle for offline backup.

Per-machine password (separate from OAuth)

Some machines (shared VMs, kiosks) require an extra password gate at the daemon level — independent of OAuth. This is per-machine, not per-account. Set with cmdop connect password set. See ./connect for the full per-machine password story.

Where credentials live

Platform	Path
macOS	`~/.cmdop/token_<mode>.json`
Linux	`~/.cmdop/token_<mode>.json`
Windows	`%APPDATA%\cmdop\token_<mode>.json`

Permissions: 0600 (owner-only). Same directory holds the discovery file, PID file, status file, and permissions ruleset. Don’t check this directory into git.

CI/CD examples

GitHub Actions:


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

GitLab CI:


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

Environment variables

Variable	Description
`CMDOP_API_KEY`	API key for non-interactive auth
`CMDOP_SERVER_ADDRESS`	Override control-plane address
`CMDOP_WORKSPACE`	Default workspace
`CMDOP_LOG_LEVEL`	Log verbosity (`debug` / `info` / `warn` / `error`)

Troubleshooting

Token expired — daemon should auto-refresh; if not, cmdop logout && cmdop login.
Wrong workspace — cmdop connect workspace use <ws> to switch.
API key invalid — cmdop auth status to verify; rotate in cabinet if needed.
Mode mismatch — cmdop mode to check, switch with cmdop mode prod or cmdop mode dev.
MFA required — cmdop auth password mfa to enrol; backup codes are shown once.