Authentication: Sign In & API Keys

oc handles authentication at two levels: OneCLI auth (your OneCLI instance) and plugin auth (service-specific credentials like Google OAuth tokens). OneCLI auth is the recommended path. Authenticate once, and oc fetches plugin credentials automatically.

OneCLI authentication

Log in

Interactive (opens browser):

oc auth login --interactive

This starts a browser-based sign-in flow. Once you authenticate, oc stores your token in your OS keychain. Device flow (for agents and headless environments):

oc auth login

{
  "status": "auth_required",
  "url": "http://localhost:10254/auth/cli?code=abc123..."
}

The agent receives a URL to present to the user. Once the user authenticates in the browser, subsequent calls to oc will work. Direct token (if you already have one):

oc auth login <token>

{
  "status": "ok"
}

Check auth status

oc auth status

{
  "authenticated": true,
  "plugins": [
    {
      "name": "google",
      "has_credentials": true
    }
  ]
}

Log out

oc auth logout

This removes your stored token from the keychain.

Plugin authentication

For plugins that support local auth, you can authenticate directly with the service:

oc google auth

The plugin runs its own OAuth or device flow. oc captures the resulting credentials and stores them securely.

Plugin auth commands are meta-commands: they run without requiring existing credentials. This lets you bootstrap auth from scratch.

How credential resolution works

When you run a plugin command like oc google calendar list-events, oc resolves credentials in this order:

Check for stored token

oc looks for a stored token (from oc auth login). If found, it requests plugin credentials from your OneCLI instance.

Fall back to local credentials

If no token exists, oc checks for locally stored credentials (from oc <plugin> auth).

Return an error with guidance

If neither source has credentials, oc returns exit code 2 with an action hint:

{
  "error": "credentials required for 'google'",
  "code": "AUTH_REQUIRED",
  "action": "oc auth login"
}

Credential storage and security

Credentials are stored using your OS keychain by default:

Platform	Backend
macOS	Keychain
Windows	Credential Manager
Linux	Secret Service (D-Bus)

If the keychain is unavailable, oc falls back to file-based storage at ~/.onecli/credentials/ with 0600 permissions (owner read/write only). What’s stored where:

Item	Keychain key	File fallback
Auth token	`onecli-token`	`~/.onecli/credentials/token`
Plugin credentials	Plugin name	`~/.onecli/credentials/{plugin}.json`

Credential injection

When oc runs a plugin command, credentials are injected as environment variables. The plugin never reads credentials from files. It receives them from the parent process environment:

OC_GOOGLE_ACCESS_TOKEN=eyJ...
OC_GOOGLE_REFRESH_TOKEN=1//...
OC_GOOGLE_TOKEN_TYPE=Bearer
OC_GOOGLE_EXPIRES_AT=2025-01-01T00:00:00Z

The naming convention is OC_{PLUGINNAME}_{FIELD}, with the plugin name and field uppercased.

​OneCLI authentication

​Log in

​Check auth status

​Log out

​Plugin authentication

​How credential resolution works

​Credential storage and security

​Credential injection

OneCLI authentication

Log in

Check auth status

Log out

Plugin authentication

How credential resolution works

Credential storage and security

Credential injection