Skip to content
Documentation
Authentication

Authentication

outline-cli supports three authentication methods. Choose based on your use case.

API Token (Recommended for CI/CD)

The simplest method. Get a token from Settings → API in Outline.

export OUTLINE_API_TOKEN=sk-your-token
export OUTLINE_SERVER_URL=https://outline.example.com
outline push --path ./docs/ --collection-id "Engineering"

OIDC Browser Login (Recommended for developers)

Interactive browser login using OAuth2 with PKCE. No token management needed — the CLI handles everything.

outline config set server_url https://outline.example.com
outline auth oidc-login

This will:

  1. Discover your Outline instance’s OAuth2 configuration
  2. Register a public OAuth2 client (Dynamic Client Registration)
  3. Open your browser for authentication
  4. Store the access token in your OS keyring

After login, all commands work without additional flags.

Basic Auth 

export OUTLINE_USERNAME=user@example.com
export OUTLINE_PASSWORD=secret
export OUTLINE_SERVER_URL=https://outline.example.com
outline push --path ./docs/ --collection-id "Docs"

Credential Resolution Order

When multiple credentials are available, this priority applies (highest wins):

  1. CLI flags (--api-token, --username/--password, --oidc-access-token)
  2. Environment variables (OUTLINE_API_TOKEN, OUTLINE_SERVER_URL)
  3. OS keyring (set via config set or auth oidc-login)
  4. Config file (~/.outline-cli/config.yaml)

Auto-Reauthentication

If your token expires during a push, the CLI automatically re-authenticates using your configured method:

outline config set auth_method oidc    # default — triggers browser login
outline config set auth_method api-token  # requires valid token in env/keyring

Verify Credentials 

outline auth check

Output:

✓ Authenticated as jane@example.com (Engineering team)

Security

  • All persisted credentials are stored in the OS keyring (libsecret on Linux, Keychain on macOS, Credential Manager on Windows)
  • Config file is written with 0600 permissions
  • If keyring is unavailable (headless/container), falls back to config file with a warning
  • Secrets are never logged; config list masks them as ***
Quick StartConfiguration