# CLI overview

> The skaas command line tool in one page. Every command by use, the exit codes, where installs go, how to roll back, signature checks and the verify command, and the prompt hook.

Source: https://skaas.io/docs/cli
Last updated: 2026-11-15

The `skaas` CLI is one npm package that needs Node 22.18 or later. It covers the author loop, the consumer loop and diagnostics. Every command accepts `--json` for machine-readable output, `--quiet`, `--no-color`, `--endpoint <url>`, `--profile <name>` and `--debug`.

## What can the CLI do?

| Command                                                                       | Purpose                                                                                                                                                                                                       |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `skaas login`, `skaas whoami`, `skaas logout`                                 | Sign in with a device flow, show who you are, and sign out. `logout` asks the service to revoke a browser sign-in first. A key that you gave with `--token` stays valid until you revoke it in the dashboard. |
| `skaas init`, `skaas audit`, `skaas test`, `skaas publish`                    | The author loop. `audit` and `test` run offline.                                                                                                                                                              |
| `skaas search`, `skaas add`, `skaas update`, `skaas rollback`, `skaas remove` | The consumer loop, recorded in `skaas.lock`. `add`, `update` and `rollback` check the signature of each release before they write a file.                                                                     |
| `skaas verify`                                                                | Checks every installed skill against `skaas.lock` and against the current signing keys of its organization. It is the command for CI and for a machine that you suspect.                                      |
| `skaas sync`                                                                  | Finds skills in your local directories and publishes the ones that changed. `--watch` plans again on a change.                                                                                                |
| `skaas connect <agent>`                                                       | Writes the MCP configuration for Claude Code, Codex, Cursor, VS Code, Gemini CLI or OpenCode.                                                                                                                 |
| `skaas hook install`, `uninstall`, `run`, `status`, `refresh`                 | Installs and runs the optional prompt-time suggestions.                                                                                                                                                       |
| `skaas export`                                                                | Writes a zip or a `.skill` file, with the rules of a destination applied.                                                                                                                                     |
| `skaas doctor`, `skaas config`                                                | Checks the configuration, the sign-in, the endpoints, the hook, the signature setting, the signing keys and the installed skills. Shows and changes the configuration file.                                   |

Commands exit with a code that a script can branch on.

| Code | Meaning                                                                                                                                                                                       |
| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 0    | Done.                                                                                                                                                                                         |
| 1    | An unexpected failure. Run the command again with `--debug`.                                                                                                                                  |
| 2    | The command line or an input is invalid. Nothing changed.                                                                                                                                     |
| 3    | Not signed in, or not allowed.                                                                                                                                                                |
| 4    | The named skill, file or profile does not exist.                                                                                                                                              |
| 5    | The request conflicts with the current state, such as an existing file, or a release that was withdrawn for security.                                                                         |
| 6    | A policy, plan, size or rate limit stopped it. For a signature, this is a release that is unsigned, or signed with a key that the organization does not list, while the setting is `require`. |
| 7    | A dependency is down. For a signature, this is a key list or a release record that could not be read while the setting is `require`. Run the command again later.                             |
| 8    | A digest does not match. For a signature, this is an invalid signature or a key that the organization revoked. For `verify`, it is also a file or a Claude Code copy that changed.            |

Three rules sit beside the table. `skaas hook run` never fails: a problem, a bad option included, prints nothing and exits 0, so a prompt is never held up. `skaas doctor` exits 1 when a check fails. `skaas verify` exits with the code of the worst failure that it found. A closed output pipe is not a failure: when a pager or `head` stops reading, the tool ends quietly with the exit code that the command had, which is 0 for a command that succeeded, so a failed `verify` piped to `head` still exits non-zero. The full table of signature refusals, with the code of each, is in `cli/COMMANDS.md`.

## How does `skaas test` judge a semantic match offline?

A local run has no semantic channel of its own, and a hit counts as a confident match when its similarity reaches a threshold. When you are signed in, the tool asks the service for the threshold of your deployment (the `search` member of the `whoami` answer, see [How search works](/docs/search)) and uses it. Otherwise it uses the default, 0.44. The result prints the threshold and says where it came from, and `skaas test --json` has the fields `semantic_threshold` and `semantic_threshold_source`. Nothing is sent when you are not signed in, and a service that does not answer is not an error.

## How do I sign in from a machine with no browser?

Pipe a key into `skaas login --token`, or set the `SKAAS_TOKEN` variable. The variable wins over a stored credential. A key that starts with `skaas_pat_` acts for a person. A key that starts with `skaas_svc_` acts for a service. Credentials go to the operating system keychain unless you run `skaas config set credential-store file`.

The endpoint comes from `--endpoint`, then `SKAAS_ENDPOINT`, then the profile in the configuration file, then the hosted service.

## Where do installed skills go?

`skaas add` writes files to `.agents/skills/<name>` and adds a link in `.claude/skills/<name>`. Codex, Cursor, Copilot, Gemini CLI, OpenCode and Devin read the first location. Claude Code reads the second. Use `--link copy` where a link does not work, and `-g` to install for your user. The install is recorded in `skaas.lock`.

## What does the lockfile record?

`skaas.lock` records the address, the release hash and the file list of every skill you installed, and the result of the signature check of that install in a `signature` field of the entry: `verified` with the key identifier and the algorithm, `unsigned`, or `unverifiable`. An install made with `signatures` set to `off` looked at nothing, so its field is `null`. The field holds no time, so installing the same release twice writes the same file. It records an earlier check and proves nothing by itself, because the lockfile is a text file that anyone can edit. `skaas verify` checks again.

Earlier versions of the tool kept that result in a separate file for each skill, `.skaas/signatures/<name>.json`. The tool no longer writes it. A lockfile that an earlier version wrote has entries without the field, and it still works. The next install that writes the lockfile reads each such file once, copies the record into the entry that it describes, and removes the file. A record that describes another release than the one in the lockfile is dropped. Until then, `skaas verify` reads the old file when an entry has no field. When neither exists, `verify` still checks the signature as it stands now and prints no "at install" line. Commit the lockfile, and a teammate who runs the same install gets the same files. If the installed files stop matching the lockfile, `skaas doctor` names what is missing, changed or extra, and `skaas verify` fails.

`skaas update` compares the lockfile with the channel, shows the file diff and the audit change, and applies the update in one step. Use `--dry-run` to see the plan only. It keeps the previous release on your machine.

## How do I install one exact release?

Name the release hash in the address, with the prefix `sha256:` and all 64 lowercase hex characters. A bare hash is refused, and so is `sha256:` followed by fewer than 64 characters.

```sh
skaas add acme/platform/code-review@sha256:<64 hex characters>
skaas add acme/platform/code-review --pin <64 hex characters>
```

The second form takes the hash that a search printed, without the prefix, and fails unless the address names that release now. An address can also end in `@<channel>` or `@<version>`. `skaas add` takes several addresses. It tries every one, prints each refusal, and exits with the code of the first refusal.

## How do I go back to an earlier release?

Run `skaas rollback <name>`. It puts the skill back to the release that `update` kept, with no network needed. To go to another release, name it with `--to`, as a version or a release hash.

```sh
skaas rollback code-review
skaas rollback code-review --to 1.2.0
```

Before it changes anything, `rollback` checks every file against the hash that the lockfile pins, and then swaps the directory in one step. It refuses when you edited the installed files by hand, because the swap would set your changes aside. Copy the directory, then add `--force`. It also refuses a release that the service says was withdrawn, and says so. If the service cannot answer, the rollback goes ahead and reports the withdrawal check as unchecked, and a signature that cannot be read is a warning under `warn`. Under `require` the rollback also needs the key list, and it exits with code 7 when it cannot reach it. `--dry-run` shows what would change.

## What does the prompt hook do?

The hook is optional. It matches each prompt against a local catalog of skill names and descriptions and suggests at most three skills. It stays silent on a prompt shorter than 12 or longer than 8,000 characters, on a greeting, on a weak match and on any error. It never changes your prompt.

`skaas hook install` supports Claude Code, Codex and Gemini CLI. Cursor, VS Code and OpenCode have no prompt hook that can add context, so they use `skaas connect`. The catalog cache holds metadata only, at most 20 MiB and 50,000 skills. It refreshes in the background, and those requests carry no prompt text. `skaas hook status` shows its state.

### Can the hook run without Node?

Yes. The package can compile the hook into one executable, so a prompt does not start Node. Build it from the package and point the hook at it.

```sh
node scripts/build-binary.mjs dist
skaas hook install --binary dist/skaas-hook-<os>-<cpu>
```

`node scripts/build-binary.mjs --list` shows the platforms: macOS on Apple silicon and Intel, Linux on x86-64 and ARM64 (glibc and musl) and Windows on x86-64. The compiled file answers `hook run` and `hook refresh` only. `--bundle` runs the hook bundle with Node instead.

### What does the remote fallback send?

By default your prompts stay on your machine. The remote fallback is off until you run `skaas config set hook-remote-fallback true`. When it is on and the local catalog has no confident match, the hook asks the service. That includes a fresh cache with nothing that fits. It sends at most 2,000 characters of the prompt, once, to the endpoint of your profile, with your credential. It asks the service to abstain below the confidence that the local match needs, and it gives up after 800 milliseconds. With no credential, nothing is sent.

## Are releases signed, and does the CLI check?

Organizations can sign releases. See [Signed releases](/docs/signed-releases). `skaas add`, `skaas update` and `skaas rollback` check the signature of each release before they write a file. `skaas update --dry-run` and `skaas rollback --dry-run` check too, so a preview never promises an install that would be refused. The CLI computes the release hash from the files that it downloaded, reads the public keys of the publishing organization, and checks the signature against them.

The **signatures** setting says what an unsigned release, or one that cannot be verified, means.

| Setting   | What the CLI does with a release that is unsigned or that it cannot verify                    |
| --------- | --------------------------------------------------------------------------------------------- |
| `require` | Refuses to install it. Nothing is written.                                                    |
| `warn`    | Installs it and prints a warning that says why it could not be verified. This is the default. |
| `off`     | Does not look at signatures and does not ask the service for them. Nothing is printed.        |

Set it for one command with `--signatures <mode>`, for a shell or a CI job with the `SKAAS_SIGNATURES` variable, or for every command with `skaas config set signatures <mode>`. The flag wins over the variable, the variable over the configuration file, and the file over the default.

Two findings are refused under `require` and under `warn`, and only `off` lets them through: a signature that does not verify, and a signature made with a key that the organization revoked. Both exit with code 8. A retired key is fine, because it signed what it signed while it was valid. A release that is unsigned exits with code 6 under `require`. A release that names a key that the organization does not list exits with code 6 under `require` and installs with a warning under `warn`. A key list or a release record that cannot be fetched exits with code 7 under `require`, and the hint says to run the command again. A credential that the service refuses, or that may not read the release record, ends the command with code 3 under `require` and under `warn`, because that says what is wrong and is not a release of unknown signature. Not being signed in ends the command with code 3 under `require` as well, because the release record cannot be read without a sign-in. Under `off` the record is not read at all. The key list is read without a credential first. The service answers `NOT_FOUND` to a stranger when the organization has nothing public, so that it does not show that the organization exists, and only then does the CLI ask again with your credential, which lets a member read the keys of private releases.

The key lists are cached for five minutes. When a signature names a key that the cached list lacks, the CLI asks the service once more before it calls the key unknown, so a rotation between two commands does not look like a stranger's key. The consequence is that a revocation can go unseen by `add`, `update` and `rollback` for up to five minutes. `skaas verify` never uses the cache.

The check shows that the files are the ones that the organization signed. It does not show that the service is honest, because the key list comes from the same service as the signature, and it does not show that a skill is safe. See [the audit and its limits](/docs/auditor).

### How do I check what is installed?

```sh
skaas verify
skaas verify code-review --signatures require
```

`verify` checks every installed skill, or the ones that you name, against `skaas.lock` and against the keys that the organization lists now. It reports the files (missing, changed, extra), the copy in the Claude Code location, and the signature, and it prints what was recorded at install next to what it found now. A changed file, a changed copy that Claude Code reads, an invalid signature and a revoked key make it exit with code 8. Under `require`, an unsigned release exits with 6, and an unreachable key list with 7. A release that the service says was withdrawn for security exits with 5. Not being signed in exits with 3. With `--signatures off` it only compares files and needs no network. Use `--dir <directory>` for another project and `-g` for your user.

For a pipeline, run `skaas verify --signatures require` after the install step.

## Which settings does the CLI keep?

The configuration file holds the settings. `skaas config path` prints its place, `skaas config show` prints what is in force, and `skaas config set <key> <value>` changes one. The value `unset` removes a profile key.

- `endpoint`: the REST API of the service, an https URL or an http URL for localhost. The default is `https://api.skaas.io`. `SKAAS_ENDPOINT` and `--endpoint` beat it.
- `mcp-endpoint`: the MCP server, in the same forms. By default it is derived from the endpoint: a leading `api.` label becomes `mcp.`, and any other endpoint is a self-hosted one, which serves the reading endpoint at `<endpoint>/mcp`. Set this key only when the operator moved the address with `SKAAS_MCP_URL`. An endpoint that you give with `SKAAS_ENDPOINT` or `--endpoint` drops the stored value.
- `org` and `repo`: the organization and the repository that commands use when an address or `--repo` names none. Both are unset by default.
- `default-profile`: the profile that commands use when none is named. The default is `default`. `SKAAS_PROFILE` and `--profile` beat it.
- `credential-store`: `keychain` (the default) or `file`. It says where the sign-in is kept.
- `signatures`: `require`, `warn` (the default) or `off`. It says what `add`, `update`, `rollback` and `verify` do about the signature of a release. `SKAAS_SIGNATURES` and `--signatures` beat it.
- `hook-remote-fallback`: `true` or `false` (the default). When it is on and the local catalog has no confident match, the prompt hook may send at most 2,000 characters of a prompt to the service.
- `config add-sync-root` and `config remove-sync-root`: the directories that `skaas sync` walks. Without any, it walks the skill directory of each agent, in your home directory and in the working directory. `--root` beats them.

## Which variables does the CLI read?

- `SKAAS_TOKEN`: a key to sign in with. It is always taken for a key, and it beats every stored credential.
- `SKAAS_ENDPOINT`: the API endpoint. It beats the endpoint of the profile, and `--endpoint` beats it.
- `SKAAS_PROFILE`: the profile of the configuration file to use. It beats `default-profile`, and `--profile` beats it.
- `SKAAS_SIGNATURES`: `require`, `warn` or `off`. An empty value is not set. It beats the `signatures` setting, and `--signatures` beats it.
- `SKAAS_CONFIG_DIR` and `SKAAS_CACHE_DIR`: the directory of the configuration file, and the directory of the caches (the hook catalog and the public keys of organizations). Each beats the directory of the platform.
- `NO_COLOR` with any value, or `TERM=dumb`: turns color off, as `--no-color` does.

The complete list of commands, flags, settings and exit codes is `cli/COMMANDS.md` in the repository. It is generated from the command definitions, and a test fails when it is out of date.

## What if something is wrong?

Run `skaas doctor`. It checks the configuration, the sign-in, whether the endpoints answer, the hook and the installed skills against `skaas.lock`. It also reports the signature setting, and for the organization of your profile and every organization that an installed skill came from it tries to fetch the signing keys and says how many are active, retired and revoked. A key list that it cannot reach is a failed check unless signatures are off.

Without a sign-in, `skaas search` searches the public catalog by words, and `skaas add` installs the current release of an approved public skill. `skaas verify` checks installed files without a sign-in; the public API does not expose the release signature or withdrawal state. Verification exits 0 under the default `warn` policy, and 3 under `require` when the release record needs a sign-in.

## Key rotation and address imports

`skaas key rotate <token-id> --org acme --overlap 300` returns a replacement secret once. It preserves scopes, repository restrictions and original expiry. Replace the key in clients before the displayed deadline. See [key rotation](/docs/key-rotation).

`skaas import https://example.com/skills.zip --repo acme/platform --kind archive` creates drafts once. Use `--kind git` for GitHub HTTPS repositories or `--kind well_known` for a skill index. The result lists every successful and refused item, and a partial result exits 1. Review the drafts in the dashboard before promoting or discarding. See [address imports](/docs/import-from-address). The command reference is generated from the CLI definitions.
