CLI Reference

The shared-context-ai CLI lets you search, install, and manage AI skills from your terminal. It's designed to be used both by humans and programmatically by AI coding agents.

Installation

The CLI is published on npm as shared-context-ai. You can run it directly with npx or install it globally:

# Run without installing
npx shared-context-ai

# Install globally
npm install -g shared-context-ai

# Both binary names work
shared-context-ai status
sc status

The package is a single-file CommonJS bundle (~67KB) with all dependencies included, so installation is fast and has no peer dependencies.

Authentication

Most commands work without authentication (using the public API for published skills), but signing in unlocks the full feature set: organization-scoped search, server-tracked installations, and update checking.

Authentication uses a browser-based OAuth flow:

Run sc login (or sc init for first-time setup)
A browser window opens to the Shared Context sign-in page
Sign in with Google OAuth
The browser redirects to a local callback server on your machine
A token is stored securely at ~/.config/shared-context/auth.json

Alternatively, if you have an auth code (e.g., from a remote environment), use:

sc login --code YOUR_AUTH_CODE

Security Auth tokens are stored with chmod 600 permissions (owner-only read/write). The login flow has a 5-minute timeout.

Agent Detection

The CLI auto-detects which AI coding agent you're using. Detection follows this priority:

Explicit flag — --agent claude-code overrides everything
Environment variables — Checks for CLAUDE_CODE, CURSOR, CODEX, OPENCODE
Home directory — Looks for ~/.claude/, ~/.cursor/, ~/.codex/, ~/.opencode/

Agent	Env Var	Directory	Platform
Claude Code	`CLAUDE_CODE`	`~/.claude/`	`claude_code`
Cursor	`CURSOR`	`~/.cursor/`	`custom`
Codex	`CODEX`	`~/.codex/`	`codex`
OpenCode	`OPENCODE`	`~/.opencode/`	`custom`

Output Modes

The CLI adapts its output format based on context:

--human — Aligned tables and human-readable text (default in a terminal)
--json — Machine-readable JSON envelope (default when piped or in a non-TTY context)

The JSON output uses a consistent envelope structure:

{
  "ok": true,
  "command": "search",
  "data": [ ... ],
  "errors": []
}

Configuration

Configuration files are stored in ~/.config/shared-context/:

File	Purpose
`auth.json`	Authentication token, user email, org info
`manifest.json`	Local installation manifest (enables anonymous installs)

The API base URL defaults to https://app.sharedcontext.ai and can be overridden for development or self-hosted instances.

Commands

`sc init`

Initialize Shared Context for your AI coding agent. This is the recommended starting point for new users.

sc init [options]

Options:
  --code <code>     Auth code from the web app (skip browser OAuth)
  --agent <agent>   Agent to configure (claude-code, cursor, codex, opencode)
  --project         Install to project directory instead of global

This command performs several steps in sequence:

Authenticates you (opens browser or uses --code)
Detects your AI coding agent
Registers the agent as a connection on the server
Installs a meta-skill that teaches the agent the search → preview → install workflow
Saves configuration locally

The meta-skill is installed to ~/{agentDir}/skills/shared-context/SKILL.md and enables your AI agent to discover and install skills on your behalf.

`sc login`

Authenticate with Shared Context.

sc login [options]

Options:
  --code <code>     Use an auth code directly (skip browser)

Opens a browser window for Google OAuth sign-in. After authentication, the token is stored locally. If you're in an environment where a browser can't open, use the --code flag with an auth code generated from the web app.

`sc search <query>`

Search for skills in the library.

sc search <query> [options]

Options:
  --type <type>     Filter by resource type (skill, file)
  --tag <tag>       Filter by topic tag
  --limit <n>       Max results (default: 20)

Examples:
  sc search "code review"
  sc search api --type skill --limit 5
  sc search testing --tag python

When authenticated, searches across your organization's skills and the public library. When anonymous, searches only published skills. Results display as a table showing the skill path, title, star count, and install count.

`sc preview <path>`

Preview a skill's full content before installing.

sc preview <path>

Examples:
  sc preview skills/api-testing
  sc preview skills/acme/code-review

Displays the complete skill content (with YAML front matter stripped). Works for both authenticated and anonymous users. Use this to evaluate a skill before deciding to install it.

`sc install <path>`

Install a skill to your AI agent's configuration directory.

sc install <path> [options]

Options:
  --project         Install to project directory instead of global
  --agent <agent>   Override agent detection

Examples:
  sc install skills/api-testing
  sc install skills/acme/api-testing --project

This command:

Fetches the skill content from the server
Writes the skill file(s) to the detected agent's skills directory
Records the installation on the server (if authenticated)
Updates the local manifest for future update tracking

By default, skills install globally (e.g., ~/.claude/skills/api-testing/). Use --project to install relative to the current directory instead.

`sc list`

List all installed skills.

sc list
sc ls     # alias

When authenticated, fetches the server-side installation list with update availability indicators. When anonymous, reads from the local manifest only and suggests signing up for full features.

`sc check`

Check for available skill updates.

sc check

Requires authentication. Compares your installed skill versions (commit SHAs) against the latest versions on the server and reports which skills have updates available.

`sc update [slug]`

Update installed skills to the latest version.

sc update [slug] [options]

Options:
  --project         Update in project directory
  --agent <agent>   Override agent detection

Examples:
  sc update              # Update all skills with available updates
  sc update api-testing  # Update a specific skill

Fetches the latest version from the server, writes updated files to disk, records the update server-side, and updates the local manifest. Run without arguments to update all skills that have pending updates.

`sc uninstall <slug>`

Remove an installed skill.

sc uninstall <slug> [options]

Options:
  --project         Uninstall from project directory
  --agent <agent>   Override agent detection

Examples:
  sc uninstall api-testing

Removes the skill files from disk, records the uninstall on the server (if authenticated), and updates the local manifest. On the server, the installation record is soft-deleted (status set to uninstalled) so reinstalling later restores it.

`sc status`

Show current CLI status and configuration.

sc status

Displays:

Authentication state (email, organization)
API base URL
Detected AI agents
Configured agent
Number of installed skills

`sc logout`

Sign out and clear stored credentials.

sc logout

Removes the authentication token from ~/.config/shared-context/auth.json. Installed skills remain on disk; only the server connection is cleared.

Workflows

First-Time Setup

The recommended way to get started is with sc init, which handles authentication, agent detection, and meta-skill installation in one step:

# Typical setup flow
sc init

# If in a headless environment, get a code from the web app first
sc init --code abc123

# Force a specific agent
sc init --agent claude-code

Discover & Install Skills

The typical workflow for finding and installing skills:

# Search for skills
sc search "code review"

# Preview a skill before installing
sc preview skills/code-review-checklist

# Install it
sc install skills/code-review-checklist

# Verify installation
sc list

Keep Skills Updated

Skill authors may push improvements at any time. Stay current with:

# Check what's changed
sc check

# Update everything
sc update

# Or update a specific skill
sc update code-review-checklist

Agent Integration

The CLI is designed for AI agents to use programmatically. After sc init installs the meta-skill, your AI agent can run CLI commands on your behalf. The typical agent workflow is:

Agent reads the meta-skill instructions
Agent runs sc search <query> --json to find relevant skills
Agent runs sc preview <path> --json to evaluate content
Agent runs sc install <path> --json to install the skill
Skill is immediately available for the agent to reference

The --json flag is auto-enabled in non-TTY contexts (like when an agent runs a command programmatically), so agents always get structured output without needing to parse tables.

Anonymous usage The CLI supports anonymous installs (without authentication) using the public API. Anonymous users can search published skills, preview content, and install locally. Server-side tracking and update checking require authentication.