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.

By The SKaaS team. Last updated . Markdown version

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?

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.

What can the CLI do?
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) 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.

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.

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.

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. 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.

Are releases signed, and does the CLI check?
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.

How do I check what is installed?

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.

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. The command reference is generated from the CLI definitions.