Skip to main content
The Better Skills CLI uses OAuth 2.0 device-code flow for authentication. This provides a secure, browser-based login that works in terminal environments without requiring you to paste tokens.

​
Login with Device-Code Flow

The login command initiates an OAuth device-code flow: 
better-skills login

​
How Device-Code Flow Works

  1. Request authorization code - CLI requests a device code from the server
  2. Open browser - CLI automatically opens your browser to the verification URL
  3. Authorize in browser - You confirm the login in your browser
  4. Poll for token - CLI polls the server for an access token
  5. Save session - Token is saved to local config directory

​
Manual Browser Opening

If the browser doesn’t open automatically:
  1. Copy the verification URL from the terminal
  2. Open it in your browser manually
  3. Enter the code if prompted
  4. The CLI will detect the authorization and continue

​
Polling Behavior

The CLI polls the server every 1-5 seconds (based on server response). Status updates include:
  • authorization_pending - Still waiting for browser confirmation
  • slow_down - Server requested slower polling (interval increases by 5s)
  • access_denied - Login was denied in the browser
  • expired_token - Login code expired (run login again)

​
Logout

The logout command signs you out and clears your local session: 
better-skills logout
This command:
  1. Sends a sign-out request to the server (if reachable)
  2. Deletes the local session file
  3. Works even if the server is unreachable

​
Check Current Session

The whoami command displays your current session info: 
better-skills whoami
Use whoami to verify your session before running other commands.

​
Session Storage

Sessions are stored as JSON in: 
~/.config/better-skills/session.json
Or, if XDG_CONFIG_HOME is set: 
$XDG_CONFIG_HOME/better-skills/session.json

​
Session Format

The session file contains: 
{
  "version": 1,
  "accessToken": "<token>",
  "tokenType": "Bearer",
  "createdAt": "2024-03-15T10:30:00.000Z",
  "expiresAt": "2024-03-15T18:30:00.000Z"
}
Never commit session.json to version control. It contains your access token.

​
SERVER_URL Configuration

By default, the CLI connects to http://localhost:3000. To connect to a different server: 
export SERVER_URL=https://api.betterskills.ai
better-skills login
The CLI uses @better-skills/env/cli for runtime config, which respects:
  1. Environment variable SERVER_URL
  2. .env file in the project root
  3. Default value http://localhost:3000

​
Authentication Flow Diagram

​
Troubleshooting

​
Browser Doesn’t Open

If the CLI can’t open your browser automatically:
  1. Copy the verification URL from the terminal
  2. Open it manually in any browser
  3. The CLI will continue polling

​
Session Expired

If you see “session invalid or expired”: 
better-skills login
Sessions expire after 8 hours by default.

​
Server Unreachable

If the CLI can’t reach the server:
  1. Check your SERVER_URL environment variable
  2. Verify the server is running
  3. Check network connectivity
better-skills health

​
Permission Denied

If you can’t write to ~/.config/better-skills/:
  1. Check directory permissions
  2. Set XDG_CONFIG_HOME to a writable directory
  3. Run with appropriate user permissions

​
Next Steps

Skill Commands

Start managing skills after authentication

Sync Workflow

Configure automatic skill syncing

Build docs developers (and LLMs) love

Get started for freeTalk to us