Authentication

Connect to Lexicon Hub to search, download, and publish knowledge packages.

tip

Browsing and downloading public packages does not require authentication. You only need to log in to publish packages or access private content.

chaoscypher lexicon login

This starts the Device Authorization flow (recommended) — a browser window opens for secure authentication.

# Start device authorization flow
curl -X POST "http://localhost:8080/api/v1/lexicon/auth/device" \
  -H "Content-Type: application/json" \
  -d '{"lexicon_url": "https://lexicon.example.com"}'

Authentication Methods

Device Authorization (Recommended)

The default and most secure method. Uses OAuth 2.0 Device Authorization Grant (RFC 8628).

chaoscypher lexicon login

Lexicon Login

╭──────────── Browser Authentication ────────────╮
│                                                 │
│ To authenticate, visit:                         │
│                                                 │
│   https://lexicon.example.com/device?code=ABCD  │
│                                                 │
│ Code expires in 15 minutes.                     │
╰─────────────────────────────────────────────────╯

Open browser automatically? [Y/n]: y
Browser opened. Complete authentication there.

⠋ Waiting for browser authentication...

✓ Logged in as jane
  Lexicon: https://lexicon.example.com
  Credentials saved to: ~/.config/chaoscypher/auth.json

If you can't open a browser (e.g., SSH session), use --no-browser and copy the URL manually:

chaoscypher lexicon login --no-browser

Token Authentication (CI/CD)

For automated pipelines, provide an API token directly:

chaoscypher lexicon login --token ghp_xxxxx

curl -X POST "http://localhost:8080/api/v1/lexicon/auth/token" \
  -H "Content-Type: application/json" \
  -d '{"token": "eyJhbGciOiJIUzI1NiIs...", "username": "ci-bot"}'

Check Status

Verify your current authentication state:

chaoscypher lexicon whoami

Logged in as: jane
  Lexicon: https://lexicon.example.com

curl "http://localhost:8080/api/v1/lexicon/auth/status"

{
  "authenticated": true,
  "username": "jane",
  "lexicon_url": "https://lexicon.example.com",
  "token_present": true
}

Logout

chaoscypher lexicon logout

curl -X POST "http://localhost:8080/api/v1/lexicon/auth/logout"

Credential Storage

Lexicon login state is stored locally in auth.json in the config directory:

Platform	Path
Linux	`~/.config/chaoscypher/auth.json`
macOS	`~/Library/Application Support/chaoscypher/auth.json`
Windows	`%LOCALAPPDATA%\chaoscypher\chaoscypher\auth.json`

The file contains the access token and Hub URL (permissions 0600 on Unix). It is created on login and removed on logout. Setting the CHAOSCYPHER_CONFIG_DIR environment variable overrides the config directory; chaoscypher lexicon login prints the exact path it saved to.

Upgrading

Earlier releases stored this in credentials.json. There is no migration — run chaoscypher lexicon login once to create auth.json. A leftover credentials.json is never read; it triggers a one-line re-login notice and can be deleted.

Hub URL Configuration

By default, the CLI connects to https://lexicon.chaoscypher.com. To use a different Hub instance:

Per-command:

chaoscypher lexicon login --url https://lexicon.example.com

Environment variable:

export LEXICON_URL=https://lexicon.example.com

Settings file (settings.yaml):

lexicon:
  url: https://lexicon.example.com
  api_path: /api/v1
  timeout: 60

Login​

Authentication Methods​

Device Authorization (Recommended)​

Token Authentication (CI/CD)​

Check Status​

Logout​

Credential Storage​

Hub URL Configuration​

Login