CLI Authentication Guide¶

Learn how to authenticate with the SkillMeat CLI. This guide covers logging in with your browser, using personal access tokens for headless environments, managing credentials securely, and troubleshooting common authentication issues.

Table of Contents¶

Quick Start
Authentication Methods
Device Code Flow (Browser Login)
Personal Access Tokens (PAT)
Credential Storage
Environment Variables
Zero-Auth Mode
Verify Your Authentication
Troubleshooting
Logout

Quick Start¶

The fastest way to authenticate:

skillmeat auth login

This launches your browser to authorize your device. Complete the flow in ~30 seconds and you're ready to use the CLI.

If you're in a headless environment (CI server, remote host, container), use a personal access token instead:

skillmeat auth token sk_live_your_token_here

Authentication Methods¶

SkillMeat CLI supports two ways to authenticate:

Method	Use When	Expiry	Setup Time
Device Code Flow (login)	Interactive terminal with browser access	Yes (configurable)	~30 seconds
Personal Access Token (PAT)	CI/CD, headless servers, containers	No (PATs don't expire)	~5 seconds

Check Your Current Mode¶

SkillMeat operates in one of two auth modes:

Clerk Mode (default): Requires authentication. Run skillmeat auth login or skillmeat auth token.
Local Mode (zero-auth): No authentication required. Works out of the box for personal/local use.

If you see a message that "SkillMeat is running in local (zero-auth) mode," you don't need to authenticate. Skip to Zero-Auth Mode.

The device code flow is the standard way to log in with your browser. It's secure and straightforward.

skillmeat auth login

You'll see a prompt like:

┌─ Authorize SkillMeat ─────────────────────────┐
│                                                │
│ To log in, visit:                             │
│                                                │
│   https://auth.example.com/authorize          │
│                                                │
│ Enter code:                                   │
│                                                │
│   ABC-DEF-GHI                                 │
│                                                │
│ The code expires in 600 seconds.              │
└────────────────────────────────────────────────┘

What to Do¶

Browser opens automatically (unless you use --no-browser)
If your browser doesn't open, manually visit the URL shown (e.g., https://auth.example.com/authorize)
Enter the device code when prompted on the website
You'll see an input field asking for your device code (e.g., ABC-DEF-GHI)
Copy/paste the code from your terminal
Authorize the device
Click "Authorize" or follow the website's prompts
The CLI continues polling in the background
Wait for confirmation

Once you authorize, the CLI displays:

┌─ Login successful ──────────────────────────┐
│                                              │
│ Successfully logged in!                      │
│                                              │
│ Credentials stored in system keyring.        │
└──────────────────────────────────────────────┘

Advanced Options¶

If your browser doesn't open automatically:

skillmeat auth login --no-browser

The CLI won't try to open your browser. You manually visit the URL and enter the code.

Extend the Timeout¶

By default, the device code expires in 600 seconds (10 minutes). If you need more time:

skillmeat auth login --timeout 900

This gives you 15 minutes to complete the authorization. Timeout is in seconds.

Token Expiry¶

When you log in via device code flow, the issuer provides an access token with a specific lifetime. The CLI stores this and automatically uses it for API requests.

How long do tokens last? Usually 1 hour, but your auth provider determines this.
What happens when tokens expire? The CLI attempts to refresh the token using the refresh token (if one was issued). If refresh fails, you'll see an error prompting you to run skillmeat auth login again.

Personal Access Tokens (PAT)¶

Use PATs for headless environments (CI servers, Docker containers, remote machines) where browser login isn't possible.

Obtaining a PAT¶

Contact your SkillMeat administrator or organization to generate a personal access token. PATs typically have a format like:

sk_live_abc123def456ghi789

Storing a PAT¶

skillmeat auth token sk_live_abc123def456ghi789

You'll see:

┌─ Token stored ────────────────────────────────┐
│                                                │
│ Personal Access Token stored successfully!    │
│                                                │
│ Credentials stored in system keyring.         │
└────────────────────────────────────────────────┘

PAT Advantages¶

No expiry: Unlike OAuth tokens, PATs don't expire automatically
CI-friendly: Set once, use forever in your CI/CD pipelines
Portable: Easy to share (securely) across environments

Using PAT in Scripts¶

When you store a PAT with skillmeat auth token, the CLI automatically uses it for all subsequent commands. You don't need to pass it on the command line.

Set PAT via Environment Variable (Optional)¶

If you prefer not to store the PAT locally, you can pass it via environment variable:

export SKILLMEAT_AUTH_TOKEN=sk_live_abc123def456ghi789
skillmeat list

The environment variable is checked first; if it's set, stored credentials are ignored.

Credential Storage¶

The CLI stores credentials securely using your operating system's credential manager. Here's where your tokens live:

Primary: System Keyring (Recommended)¶

On most systems, credentials are stored in the platform's secure credential manager:

macOS: Keychain
Windows: Credential Manager (Credential Locker)
Linux: Secret Service (D-Bus)

This is the most secure option and is used automatically when available.

Fallback: Credentials File¶

If your system doesn't have a working keyring (e.g., headless Linux servers), the CLI falls back to:

~/.skillmeat/credentials.json

This file has restricted permissions (0600, readable/writable by owner only) for security.

Example Credentials File¶

When using the file backend, credentials are stored as plain JSON:

{
  "access_token": "eyJhbGc...",
  "token_type": "Bearer",
  "refresh_token": "refresh_...",
  "expires_at": 1741276800.0,
  "stored_at": 1741190400.0,
  "id_token": "eyJhbGc..."
}

Keep this file secret. It contains your access tokens and should never be committed to version control or shared.

Verify Credential Storage Location¶

After running skillmeat auth login or skillmeat auth token, the CLI tells you where credentials are stored:

Credentials stored in system keyring.

or

Credentials stored in ~/.skillmeat/credentials.json (mode 0600).

Environment Variables¶

The CLI respects these environment variables for authentication:

Variable	Purpose	Example
`SKILLMEAT_AUTH_TOKEN`	Override stored credentials with a PAT	`sk_live_abc123`
`SKILLMEAT_AUTH_MODE`	Force auth mode (usually auto-detected)	`clerk` or `local`
`SKILLMEAT_AUTH_ISSUER_URL`	OAuth issuer URL (for device code flow)	`https://auth.example.com`
`SKILLMEAT_AUTH_CLIENT_ID`	OAuth client ID (for device code flow)	`your-client-id`
`SKILLMEAT_AUTH_AUDIENCE`	Optional OAuth audience claim	`https://api.skillmeat.com`

Priority Order¶

When the CLI needs a token, it checks in this order:

SKILLMEAT_AUTH_TOKEN env var (if set, overrides all stored credentials)
Stored credentials (from keyring or ~/.skillmeat/credentials.json)
No credentials (unauthenticated, if allowed by server)

Zero-Auth Mode¶

If SkillMeat is running in local (zero-auth) mode, no authentication is required. You can use the CLI immediately without logging in.

When Zero-Auth Mode is Active¶

You'll see a message like:

┌─ Auth not required ───────────────────────────┐
│                                                │
│ SkillMeat is running in local (zero-auth)     │
│ mode.                                         │
│                                                │
│ No authentication is required. All API        │
│ endpoints are accessible without credentials.│
└────────────────────────────────────────────────┘

This appears when you run:

skillmeat auth login
# or
skillmeat auth token sk_live_...

Enable Authentication in Zero-Auth Mode¶

To switch from local to authenticated mode, set these environment variables and restart your SkillMeat server:

export SKILLMEAT_AUTH_MODE=clerk
export SKILLMEAT_AUTH_ISSUER_URL=https://your-auth-provider.example.com
export SKILLMEAT_AUTH_CLIENT_ID=your-client-id

Then restart the API server:

skillmeat web dev

Verify Your Authentication¶

To check if you're currently authenticated:

skillmeat auth login

If you're already logged in, it will refresh your credentials. If credentials are missing or expired, you'll be prompted to re-authenticate.

Check Stored Credentials (Advanced)¶

To inspect what's stored (without revealing the actual token):

On macOS:

# List all SkillMeat credentials in Keychain
security find-generic-password -s skillmeat-cli

On Linux with Secret Service:

# List secrets (requires appropriate tools)
secret-tool search service skillmeat-cli

On Windows:

# Use Credential Manager GUI
control.exe /name Microsoft.CredentialManager

Troubleshooting¶

"Auth not configured"¶

Error:

DeviceCodeConfigError: Auth not configured. Set SKILLMEAT_AUTH_ISSUER_URL
and SKILLMEAT_AUTH_CLIENT_ID environment variables.

Solution:

Your SkillMeat instance isn't properly configured. Either:

You're in local (zero-auth) mode — which is fine. You don't need to authenticate.
Configuration is incomplete — contact your administrator to:
Enable authentication on the server
Provide you with SKILLMEAT_AUTH_ISSUER_URL and SKILLMEAT_AUTH_CLIENT_ID
You set SKILLMEAT_AUTH_MODE=clerk but didn't set the issuer/client ID. Either remove the env var or provide the full config.

Device Code Expired¶

Error:

DeviceCodeExpiredError: The device code has expired.
Please run 'skillmeat auth login' again.

Solution:

The authorization window (usually 10 minutes) closed before you completed the flow.

Run skillmeat auth login again to get a new device code. If you consistently need more time, use the --timeout flag:

skillmeat auth login --timeout 900  # 15 minutes

Authorization Denied¶

Error:

Authorization denied. The request was cancelled.

Solution:

You clicked "Cancel" or "Deny" on the authorization page. Run skillmeat auth login again to try once more.

Credentials File Corrupted¶

Error:

Corrupt credentials file at ~/.skillmeat/credentials.json

Solution:

Your credentials file is corrupted (not valid JSON). Log out and log back in:

skillmeat auth logout
skillmeat auth login

"Could not open browser automatically"¶

Message:

Could not open browser automatically. Please visit the URL above manually.

Solution:

This is informational, not an error. The CLI tried to open your browser but failed (common on headless systems). You can safely:

Manually copy the verification_uri from the terminal
Visit it in your browser
Enter the user_code

Token Refresh Failed¶

Error:

Token refresh failed. Please run 'skillmeat auth login' again.

Solution:

Your stored refresh token couldn't be exchanged for a new access token. This usually means:

The refresh token is expired
Your auth provider revoked it
Your auth provider is temporarily down

Run skillmeat auth login to get fresh credentials.

"Permission denied" on Credentials File¶

Error:

PermissionError: [Errno 13] Permission denied: '~/.skillmeat/credentials.json'

Solution:

Your credentials file has incorrect permissions. Fix it with:

chmod 600 ~/.skillmeat/credentials.json

Then try your command again.

Wrong credentials being used¶

Issue:

The CLI is using a different token than expected.

Solution:

Check the priority order (see Environment Variables):

If SKILLMEAT_AUTH_TOKEN is set, it overrides everything. Check:
```
echo $SKILLMEAT_AUTH_TOKEN
```
If you want to use stored credentials instead, unset the env var:
```
unset SKILLMEAT_AUTH_TOKEN
```

Can't authenticate in CI/CD¶

Issue:

Device code flow doesn't work in CI because there's no browser.

Solution:

Use a personal access token (PAT) instead:

Obtain a PAT from your administrator
Set it as an environment variable in your CI:
```
export SKILLMEAT_AUTH_TOKEN=sk_live_...
```
Your CI jobs can now use the SkillMeat CLI without interactive authentication

Example GitHub Actions:

- name: Authenticate with SkillMeat
  env:
    SKILLMEAT_AUTH_TOKEN: ${{ secrets.SKILLMEAT_PAT }}
  run: skillmeat list

Example GitLab CI:

script:
  - export SKILLMEAT_AUTH_TOKEN=$SKILLMEAT_PAT
  - skillmeat list

Logout¶

Remove all stored credentials:

skillmeat auth logout

You'll see:

┌─ Logout ──────────────────────────────────────┐
│                                                │
│ Logged out successfully.                       │
│                                                │
│ All stored credentials have been cleared.      │
└────────────────────────────────────────────────┘

What Gets Cleared¶

Running logout removes:

Access token
Refresh token (if present)
Token metadata (expiry, issuance time, etc.)
Stored ID token (if present)

The CLI will no longer authenticate to the API. Your next command will either:

Use SKILLMEAT_AUTH_TOKEN env var (if set)
Work in zero-auth mode (if the server allows it)
Prompt you to run skillmeat auth login

Safe to Run Anytime¶

It's safe to run skillmeat auth logout even when:

You're already logged out
Credentials don't exist
You're in zero-auth mode

No errors will occur; the command is idempotent.

FAQ¶

Can I use the same PAT on multiple machines?¶

Yes. PATs are meant to be reused. Set the same token on all machines where you need it:

skillmeat auth token sk_live_shared_token

Each machine maintains its own copy.

How often do I need to log in?¶

It depends on your auth provider.

If tokens expire quickly (e.g., 1 hour), the CLI refreshes them automatically. You stay logged in as long as your refresh token is valid.
If tokens expire very slowly (or never), you might not need to log in again for months.
The CLI tells you when automatic refresh fails and prompts you to log in again.

Can I use multiple accounts on the same machine?¶

Not yet. The CLI stores one set of credentials per user account on your machine. If you need to switch users, run:

skillmeat auth logout
skillmeat auth login

What if I lose my device code?¶

You can't reuse it. Run skillmeat auth login again to get a new device code.

Is my token safe in `~/.skillmeat/credentials.json`?¶

Yes, with caveats.

The file has 0600 permissions (owner-only read/write)
If your system keyring is available, tokens are stored there instead (more secure)
If your home directory is encrypted, your tokens are encrypted
If your home directory is not encrypted, tokens are readable by anyone who gains filesystem access

For maximum security, prefer systems with encrypted home directories and working keyring backends (modern macOS, Windows, and Linux distributions).

Can I revoke a stored token?¶

Yes. Run skillmeat auth logout to remove the token from storage. However:

The token itself remains valid with the auth provider until it expires or is manually revoked by an admin
Removing it from local storage just prevents the CLI from using it

To fully revoke a token, contact your admin or revoke it through your auth provider's dashboard.

What happens if I delete `~/.skillmeat/credentials.json` manually?¶

The CLI will behave as if you ran skillmeat auth logout. Your next authenticated command will fail with a prompt to log in again (unless you're in zero-auth mode).

Can I use `skillmeat auth token` with OAuth tokens?¶

No. The skillmeat auth token command is for PATs only. OAuth tokens from the device code flow are stored automatically and should not be manually set.

CLI Authentication Guide¶

Table of Contents¶

Quick Start¶

Authentication Methods¶

Check Your Current Mode¶

Device Code Flow (Browser Login)¶

Step-by-Step Login¶

What to Do¶

Advanced Options¶

Login with Manual URL Entry¶

Extend the Timeout¶

Token Expiry¶

Personal Access Tokens (PAT)¶

Obtaining a PAT¶

Storing a PAT¶

PAT Advantages¶

Using PAT in Scripts¶

Set PAT via Environment Variable (Optional)¶

Credential Storage¶

Primary: System Keyring (Recommended)¶

Fallback: Credentials File¶

Example Credentials File¶

Verify Credential Storage Location¶

Environment Variables¶

Priority Order¶

Zero-Auth Mode¶

When Zero-Auth Mode is Active¶

Enable Authentication in Zero-Auth Mode¶

Verify Your Authentication¶

Check Stored Credentials (Advanced)¶

Troubleshooting¶

"Auth not configured"¶

Device Code Expired¶

Authorization Denied¶

Credentials File Corrupted¶

"Could not open browser automatically"¶

Token Refresh Failed¶

"Permission denied" on Credentials File¶

Wrong credentials being used¶

Can't authenticate in CI/CD¶

Logout¶

What Gets Cleared¶

Safe to Run Anytime¶

FAQ¶

Can I use the same PAT on multiple machines?¶

How often do I need to log in?¶

Can I use multiple accounts on the same machine?¶

What if I lose my device code?¶

Is my token safe in ~/.skillmeat/credentials.json?¶

Can I revoke a stored token?¶

What happens if I delete ~/.skillmeat/credentials.json manually?¶

Can I use skillmeat auth token with OAuth tokens?¶

Is my token safe in `~/.skillmeat/credentials.json`?¶

What happens if I delete `~/.skillmeat/credentials.json` manually?¶

Can I use `skillmeat auth token` with OAuth tokens?¶