Preview — not yet generally available. Lexicon Hub is documented now so the launch surface is final, but the hosted backend is not yet running. Self-host alternatives are described in the relevant page.

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.

Login

CLI

chaoscypher lexicon login

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

API

# 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 denis
  Lexicon: https://lexicon.example.com
  Credentials saved to: ~/.config/chaoscypher/credentials.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:

CLI

chaoscypher lexicon login --token ghp_xxxxx

API

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:

CLI

chaoscypher lexicon whoami

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

API

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

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

Logout

CLI

chaoscypher lexicon logout

API

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

Credential Storage

Credentials are stored locally at:

Platform	Path
Linux	~/.config/chaoscypher/credentials.json
macOS	~/Library/Application Support/chaoscypher/credentials.json
Windows	%APPDATA%\chaoscypher\credentials.json

The file contains the access token and Hub URL. It is created on login and removed on logout.

Hub URL Configuration

By default, the CLI connects to http://localhost:3001. 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