CLI Reference

The localskills CLI (@localskills/cli on npm) installs, publishes, and organizes skills across AI coding tools from your terminal.

login

localskills login [--token <token>] [--oidc-token <token> --team <slug>]

With no flags, starts a browser device-code flow: the CLI shows a verification code, opens the browser, and polls until you approve. Device codes expire after 10 minutes. Credentials are stored in ~/.localskills/config.json with 0600 permissions.

See CI/CD & OIDC for the OIDC exchange, which lets GitHub Actions and GitLab CI publish without storing any secret.

logout

localskills logout

Clear the stored auth token from your local configuration.

whoami

localskills whoami

Display the current authenticated user’s name, username, and email.

install

localskills install [slug] [options]

Install a skill by slug, public ID, or share URL. With no arguments, the CLI lists available skills for interactive selection; with no flags it prompts for platforms, scope, and install method.

Pin a version npm-style: my-skill@1.2.3 (exact), my-skill@^1.0.0 (semver range), or my-skill@latest.

If the skill declares required MCP servers you don’t have installed for that location and tool (user-level installs count everywhere for their tool, project installs per project, and each targeted tool needs its own entry), the CLI offers to install each one right after the skill. Requirements exist only on private team skills, so this only ever happens for members; in CI and other non-interactive runs the CLI prints the matching localskills mcp install commands instead of prompting. Declining a server never affects the skill install.

uninstall

localskills uninstall [slug] [--purge]

Remove an installed skill from all target platforms. Pass --purge to also delete the cached copy from ~/.localskills/cache/. Omit the slug for interactive selection.

list

localskills list [--public | --personal] [--tag <tag>] [--search <query>]

List skills available to you from your organizations. Pass --public to browse public skills instead; --tag and --search filter the public catalog. Pass --personal to list only skills in your managed personal workspace folders.

pull

localskills pull [slug]

Update installed skills to the latest version. Omit the slug to update everything. The CLI compares content hashes to decide whether an update is needed: symlinked installs update automatically when the cache refreshes, while copied and section-based installs are re-written in place. If any pulled skill requires MCP servers you don’t have, pull prints the matching localskills mcp install commands (it never prompts).

publish

localskills publish [path] [options]

Publish a local skill to localskills.sh. path can be a single file (published as a text skill, frontmatter stripped) or a folder (zipped and published as a multi-file package, files preserved verbatim). A skill folder must contain a SKILL.md at its root. Package limits: 100 MB compressed, 100 MB uncompressed, 500 files.

Without a path, the CLI scans your project for unpublished skills across all supported platform directories and lets you pick interactively.

By default publish is an upsert: a name that already belongs to a skill you can write to appends a new version, and anything else creates a new skill (auto-renaming the slug on collision). Automation that must never guess can pin the outcome: --create fails with E_ALREADY_EXISTS when the name is taken, and --update fails with E_NOT_FOUND when there is nothing to update, or E_AMBIGUOUS (listing the candidates in -o json details) when several same-name skills exist across folders. Pass -f to pick a folder, or target a skill id directly with push.

push

localskills push <path> --skill <id> [options]

Push a new version of an existing skill: the non-interactive counterpart to publish, built for CI pipelines. path accepts a file or a skill folder, same as publish.

localskills push skill.md --skill my-skill --patch -m "Fix typos"

share

localskills share [path] [options]

Share a skill anonymously without an account. path accepts a file or a skill folder. On first use, the CLI generates an Ed25519 keypair stored in ~/.localskills/config.json as your anonymous identity. Shared skills are always unlisted and anonymous identities are limited to 10 shared skills. See Anonymous Sharing for details.

folders

localskills folders [list|create <path>] [-t <team>]

List an organization’s skill folders with their skill counts (list is the default subcommand), or create a folder path; missing parent folders are created along the way, like mkdir -p.

move

localskills move <skill> <dest> [--parents]

Move a skill (by public ID or slug) into a folder, or back to the root with /. Pass --parents to create the destination path first:

localskills move my-skill marketing/seo
localskills move my-skill /
localskills move my-skill new/place --parents

profile

localskills profile <list|create <name>|switch <name>|delete <name>>

Manage CLI profiles for multiple accounts, for example a personal account and a work organization. Each profile keeps its own auth token, installed skills, and preferences. Profile names are lowercase alphanumeric with hyphens, up to 32 characters.

localskills profile create work
localskills profile switch work
localskills profile list

Override the active profile per command with the global --profile <name> flag or the LOCALSKILLS_PROFILE environment variable (flag wins over the environment, which wins over the config); useful in scripts and CI.

mcp

localskills mcp <list|install <ref>|uninstall <ref>|pull [ref]>

Install your team’s managed MCP servers into your AI tools. mcp list shows what your teams offer and which servers you have installed; mcp install writes the server into each detected tool’s native MCP config (Claude Code, Cursor, Windsurf, VS Code, Cline, Codex, opencode); mcp pull refreshes installs after an admin updates a server. Refs are team/slug, a bare slug when unambiguous, or the server id.

localskills mcp install acme/github -t claude,cursor
localskills mcp install acme/github --var GITHUB_TOKEN=$TOKEN   # CI
localskills mcp pull

Member-supplied values (API keys) are prompted locally and written only into the tool’s config file, never stored on localskills.sh. See MCP Servers for the full model.

Environment variables

Configuration layout

Config and cache live in ~/.localskills/:

~/.localskills/
  config.json         # Auth token(s), profiles, installed skills, preferences
  cache/
    my-skill/
      raw.md          # Original content (text skills)
      meta.json       # Hash, version, metadata
      cursor.mdc      # Platform-specific transformed files
    my-folder-skill/
      meta.json
      manifest.json   # File list for a package skill
      pkg/            # Unpacked package skill (SKILL.md + scripts/, ...)