--- title: "CLI Reference" description: "Complete CLI reference for the localskills command-line tool. Install, publish, push, share, and organize agent skills from your terminal." --- > Documentation Index > Fetch the complete documentation index at: https://docs.localskills.sh/llms.txt > Use this file to discover all available pages before exploring further. # CLI Reference The `localskills` CLI (`@localskills/cli` on npm) installs, publishes, and organizes skills across AI coding tools from your terminal. ## login ```sh localskills login [--token ] [--oidc-token --team ] ``` 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. | Flag | Description | | --- | --- | | `--token ` | Headless mode: store an API token directly (CI, containers, SSH) | | `--oidc-token ` | Exchange a CI/CD OIDC identity token for a short-lived API token | | `--team ` | Organization slug (required with --oidc-token) | See [CI/CD & OIDC](/cicd) for the OIDC exchange, which lets GitHub Actions and GitLab CI publish without storing any secret. ## logout ```sh localskills logout ``` Clear the stored auth token from your local configuration. ## whoami ```sh localskills whoami ``` Display the current authenticated user's name, username, and email. ## install ```sh 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`. | Flag | Description | | --- | --- | | `-t, --target ` | Target platforms: cursor, claude, codex, windsurf, cline, copilot, opencode, aider | | `-g, --global` | Install globally (user-level) | | `-p, --project [dir]` | Install in a project directory | | `--symlink` | Symlink from the local cache (text-install default on macOS/Linux; also the Claude Code package default) | | `--copy` | Copy content directly into the target location (default on Windows, and for package installs on non-Claude tools) | > **Note** > > For single-file text skills, GitHub Copilot and Codex CLI use the *section* > install method (embedded markers in a shared file), and Windsurf global > installs also use sections. Multi-file package skills instead install as > folder-based Agent Skills on every supported tool except aider, copied into > the tool's native skills directory by default (use `--symlink` to link to the > local cache). If the skill declares [required MCP servers](/mcp-servers#linking-servers-to-skills) 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 ```sh 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 ```sh localskills list [--public | --personal] [--tag ] [--search ] ``` 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 ```sh 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 ```sh 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. | Flag | Description | | --- | --- | | `-t, --team ` | Organization ID or slug to publish to | | `-n, --name ` | Skill display name | | `--visibility ` | public, private, or unlisted (default: private) | | `--type ` | skill or rule (default: skill) | | `-m, --message ` | Message for the initial version (default: "Initial version") | | `-f, --folder ` | Folder path to publish into (e.g. marketing/seo) | | `-p, --parents` | Create missing folders in the --folder path | | `--personal` | Publish privately into your managed personal workspace; incompatible with --folder and --parents | | `--create` | Fail if a skill with this name already exists (never update, never auto-rename) | | `--update` | Fail unless this appends a version to an existing skill (never create) | 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 ```sh localskills push --skill [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. | Flag | Description | | --- | --- | | `-s, --skill ` | Skill ID or slug (required) | | `--version ` | Explicit semver (must be greater than the current version) | | `--patch` | Bump the patch version | | `--minor` | Bump the minor version | | `--major` | Bump the major version | | `-m, --message ` | Version message | ```sh localskills push skill.md --skill my-skill --patch -m "Fix typos" ``` ## share ```sh localskills share [path] [options] ``` | Flag | Description | | --- | --- | | `-n, --name ` | Skill display name | | `--type ` | skill or rule (default: skill) | 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](/sharing) for details. ## folders ```sh localskills folders [list|create ] [-t ] ``` 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 ```sh localskills move [--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: ```sh localskills move my-skill marketing/seo localskills move my-skill / localskills move my-skill new/place --parents ``` ## profile ```sh localskills profile |switch |delete > ``` 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. ```sh localskills profile create work localskills profile switch work localskills profile list ``` Override the active profile per command with the global `--profile ` flag or the `LOCALSKILLS_PROFILE` environment variable (flag wins over the environment, which wins over the config); useful in scripts and CI. ## mcp ```sh localskills mcp |uninstall |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. ```sh 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](/mcp-servers) for the full model. ## Environment variables | Flag | Description | | --- | --- | | `LOCALSKILLS_TOKEN` | Auth token override; takes precedence over the stored token, never persisted (CI-friendly) | | `LOCALSKILLS_API_URL` | API base URL override (default: https://localskills.sh) | | `LOCALSKILLS_PROFILE` | Active profile override | | `LOCALSKILLS_NO_UPDATE_CHECK` | Set to 1 to disable the daily update check | ## Configuration layout Config and cache live in `~/.localskills/`: ```text ~/.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/, ...) ``` Source: https://docs.localskills.sh/cli/index.mdx