Authentication

Log in to SkillReg, set up your development environment, and manage your identity. Supports OAuth, API keys, and SSO for teams.

Browser Login

The default way to authenticate is through your browser. This uses an OAuth device flow: the CLI opens your browser, you log in to SkillReg, and the token is automatically saved to your local configuration.

Terminal

skillreg login

Output

Authenticating via browser...

  Your code: ABCD-1234

  Open this URL in your browser:
  https://skillreg.dev/auth/cli?code=ABCD-1234

  Browser opened automatically.

  Waiting for authorization...

  ✓ Logged in successfully!

The CLI generates a device code, displays it in the terminal, and attempts to open the verification URL automatically. Once you authorize the request in your browser, the CLI receives the token and stores it in ~/.skillreg/config.json.

Firewall or proxy issues?

If the browser does not open automatically, copy the URL from the terminal and paste it into your browser manually. If the device flow fails entirely, use skillreg login --token instead.

Token Login

For CI/CD pipelines, Docker containers, or any headless environment where a browser is not available, use token-based login. You paste an API token directly into the terminal.

Terminal

skillreg login --token

Output

To login, create an API token in the SkillReg dashboard:
  1. Go to your organization's "API Tokens" page
  2. Create a new token
  3. Copy the token and paste it below

  Token: sr_live_xxxxxxxxxxxxxxxx

  ✓ Logged in successfully!

The CLI accepts tokens with the following prefixes:

sr_live_ — Production tokens (recommended)
sr_test_ — Test/sandbox tokens
sk_ — Legacy tokens (still supported for backward compatibility)

Keep your tokens secret

Never commit API tokens to version control. In CI/CD, store them as encrypted secrets (e.g. GitHub Actions secrets, GitLab CI variables) and pass them via skillreg login --token or the SKILLREG_TOKEN environment variable.

Setup Wizard

The setup wizard combines authentication with initial CLI configuration. It walks you through four interactive steps:

Authentication — Browser login or token paste
Default organization — Selects which org to use by default (auto-detects your orgs)
Default agent — Choose between Claude, Codex, or Cursor
Install scope — Project-local or user-global installation

Terminal

skillreg setup

skillreg setup

Welcome to SkillReg! Let's set up your CLI.

Step 1/4 — Authentication

  How do you want to log in?
  ❯ Browser login (recommended)
    Paste a token manually

  ✓ Logged in successfully!

Step 2/4 — Default organization

  Select your default organization:
  ❯ Acme Corp (owner)
    Side Project (member)

  ✓ Default org set to: acme-corp

Step 3/4 — Default agent

  Which AI agent do you use?
  ❯ Claude (recommended)
    Codex
    Cursor

  ✓ Default agent set to: claude

Step 4/4 — Install scope

  Where should skills be installed by default?
  ❯ Project (recommended)
    User (global)

  ✓ Default scope set to: project

  ─────────────────────────────────
  ✓ Setup complete! Your config:

    Org:    acme-corp
    Agent:  claude
    Scope:  project

  Next steps:
    skillreg pull @acme-corp/<skill>   Pull a skill
    skillreg init my-skill             Create a new skill
    skillreg list                      List org skills

Run setup once per machine

You only need to run skillreg setup once. Your preferences are saved to ~/.skillreg/config.json and persist across sessions. If you are already logged in, the wizard detects it and skips the authentication step.

Choosing an agent

The agent setting determines where skills are installed on your filesystem:

Claude — .claude/skills/ (project) or ~/.claude/skills/ (user)
Codex — .codex/skills/ (project) or ~/.codex/skills/ (user)
Cursor — .cursor/skills/ (project) or ~/.cursor/skills/ (user)

Choosing a scope

The scope controls whether skills are installed locally to the current project or globally for your user account:

Project (recommended) — Skills are installed in the current working directory. Each project has its own set of skills.
User — Skills are installed in your home directory and are available to all projects.

Check Identity

Verify who you are logged in as, inspect your token scopes, and see which organizations you belong to:

Terminal

skillreg whoami

Output

Alice Martin
  Email: alice@acme-corp.com
  Username: @alice
  Token: CLI Token (read, write, admin)

  Organizations:
    @acme-corp — Acme Corp (owner)
    @side-project — Side Project (member)

This is useful for debugging authentication issues or confirming which token is active before running commands like push or pull.

JSON output

Add the --json flag to any command for machine-readable output: skillreg whoami --json

Non-Interactive Configuration

If you prefer to set configuration values directly without the interactive wizard, use the config command. This is especially useful in scripts and CI/CD pipelines.

skillreg config

Set CLI configuration values without the interactive wizard.

Flag	Description	Default
--org <slug>	Set the default organization for all commands	—
--api-url <url>	Set the API base URL (for self-hosted registries)	https://skillreg.dev
--default-agent <agent>	Set the default AI agent: claude, codex, or cursor	claude
--default-scope <scope>	Set the default install scope: project or user	project

You can set multiple options in a single call:

Terminal

skillreg config --org acme-corp --default-agent claude --default-scope project

Output

✓ Configuration saved

Or set values one at a time:

Terminal

skillreg config --org my-new-org

CI/CD example

A typical CI/CD setup combines token login with non-interactive configuration:

ci-pipeline.yml

# Authenticate with a stored secret
skillreg login --token <<< "$SKILLREG_TOKEN"

# Set the target organization
skillreg config --org acme-corp

# Pull skills needed for the pipeline
skillreg pull @acme-corp/code-review
skillreg pull @acme-corp/test-generator

Configuration file location

All configuration is stored in ~/.skillreg/config.json. You can inspect or back up this file directly if needed.