CLI reference

The baselane CLI. Every command below is generated from the real USAGE string the CLI itself prints for --help:

usage:
  baselane audit <dir> [--json] [--exclude <patterns>]
  baselane apply <dir> (--pack <id> | --pack-file <path>) [--force] [--dry-run]
  baselane distribute <owner/repo> (--pack <id> | --pack-file <path>) [--portal <url>]
  baselane draft-pack <dir> [--json]
  baselane graph <dir> [--json] [--exclude <patterns>]
  baselane map <dir> [--json] [--llm] [--dry-run] [--exclude <patterns>]
  baselane install [github:owner/repo@ref | @scope/name[@version] | owner/repo@skill] [-g] [--dir <d>] [--dry-run] [--json]
  baselane update [github:owner/repo | @scope/name] [-g] [--dir <d>] [--dry-run]
  baselane drift [-g] [--dir <d>] [--json]
  baselane publish @scope/name --source github:owner/repo --ref <tag> [--registry URL] [--json]

Install

baselane install <source> [-g] [--dir <d>] [--dry-run] [--json] resolves one of three source forms and writes (or updates) the manifest's packs entry:

• github:owner/repo@ref: records the exact git ref (tag, branch, or sha) of that repo — one fixed point, never a range. Baselane calls this a pin. If the resolved fileset has a root pack.json, that file is the pack. Otherwise baselane builds the pack from AGENTS.md/.claude/ content (see the pack format page).
• @scope/name[@version]: a registry package. With no @version, resolves to the highest published semver version. Baselane looks up the registry entry, re-resolves its recorded source, and checks the resulting sha against what the registry recorded at publish time. A mismatch fails loudly instead of installing silently different content.
• owner/repo@skill: imports a single named skill out of that repo, pinned to its default branch (no explicit ref). If skill doesn't match one, it fails and lists every available skill.

• -g / --global: targets the machine manifest (~/.baselane/harness.json, materializing into ~/.claude/) instead of the current repo's root harness.json.
• --dry-run: reports what would be written, without touching disk.
• --json: prints the install report as JSON (log notices move to stderr so stdout stays pure JSON).

Example: the three source forms, each run on its own.

baselane install @acme/security-review
baselane install github:acme/security-review-pack@v1.1.0
baselane install acme/security-review-pack@code-review

Each one writes (or updates) a packs entry in harness.json and puts the pack's files into .claude/. On success it prints wrote N file(s), removed 0, backed up 0 drifted, left 0 unchanged. The third form pulls only the code-review skill out of acme/security-review-pack's default branch. It does not pull the whole pack. Add -g to install into ~/.claude/ instead of the repo. Add --dry-run to preview without writing anything.

Update

baselane update [github:owner/repo | @scope/name] [-g] [--dir <d>] [--dry-run] re-resolves and re-materializes everything already pinned in harness.json (or just the one named pack, if given), same target rules as install.

Example:

baselane update
baselane update @acme/security-review

With no name, every pinned pack gets checked again. If a git ref moved (a tag was moved, a branch moved forward), the pack picks up the new sha. Every registry pack is checked for a newer published version and moved to it. Give a name to limit the printed report (updated ... old-sha to new-sha or unchanged ...) to that one pack. The check itself still covers the whole manifest either way.

Drift

baselane drift [-g] [--dir <d>] [--json] compares what's on disk against the manifest's materialized receipt: vendored file hashes, managed-region content/version hashes, and capability receipt hashes. It exits 0 when clean, and 1 when drift is detected. Wire it into CI to catch a hand-edited vendored file or a stale region before it ships.

Example:

baselane drift

If nothing has changed on disk since the last install or update, it prints baselane drift: clean (N vendored file(s), N region(s) verified) and exits with code 0. If a vendored file was hand-edited, or a managed region fell out of sync, it prints baselane drift: DRIFT DETECTED (...) with one line per drifted path, and exits with code 1. Use this as a CI check next to baselane update.

Publish

baselane publish @scope/name --source github:owner/repo --ref <tag> [--registry URL] [--json] publishes a version to the registry:

• GITHUB_TOKEN is required: publish has no unauthenticated path.
• --ref must be a semver version tag (optionally v-prefixed, e.g. v1.2.0). A branch name, sha, or arbitrary ref is rejected outright, since the registry only accepts strict X.Y.Z versions.
• The namespace (@scope) must match the authenticated GitHub user or org behind GITHUB_TOKEN, or the registry returns 403.
• Publishing the same name@version twice returns 409. Bump the tag and try again.

Example (you need GITHUB_TOKEN set):

baselane publish @acme/security-review --source github:acme/security-review-pack --ref v1.1.0

This looks up v1.1.0 on acme/security-review-pack, turns it into a sha, builds the pack from those files, and sends it to the registry as @acme/security-review@1.1.0. On success it prints published @acme/security-review@1.1.0 (sha <short-sha>) and exits with code 0. If you publish the same name and version again, it prints a "version already published" message and exits with code 1.

Everything else

• baselane audit <dir>: profiles a repo's languages, frameworks, and commands.
• baselane apply <dir> (--pack <id> | --pack-file <path>): writes a built-in or custom pack's files directly. No manifest or registry is involved.
• baselane distribute <owner/repo> ...: opens a PR against a target repo with a pack's files, and can optionally report adoption to a portal.
• baselane graph / baselane map: compute the dependency graph and ARCHITECTURE.md/DESIGN.md respectively. map takes --llm for AI narration. It needs ANTHROPIC_API_KEY (or BASELANE_ANTHROPIC_KEY, which keeps that key separate from other tools that read ANTHROPIC_API_KEY).
• baselane draft-pack <dir>: drafts a starter pack.json from a repo's own conventions. It is a starting point to hand-edit and publish, not something that installs or publishes on its own.

Examples:

baselane audit .
baselane apply . --pack security-review
baselane distribute acme/some-service-repo --pack security-review
baselane draft-pack .
baselane graph .
baselane map . --llm

audit prints a report of languages, frameworks, and commands, and ends with one recommended built-in pack. apply writes that pack's files straight into . and prints wrote N file(s). It leaves existing files alone unless you add --force. distribute opens a pull request on acme/some-service-repo with the pack's files and prints the pull request URL. It needs GITHUB_TOKEN set. draft-pack prints a starter pack.json built from the repo's own conventions, for you to hand-edit and publish later. graph writes .baselane/graph.json and .baselane/graph/GRAPH.md, then prints a summary of modules, edges, and fan-in. map --llm writes ARCHITECTURE.md (and DESIGN.md, if it finds a UI surface) with AI narration. Set ANTHROPIC_API_KEY (or BASELANE_ANTHROPIC_KEY) first, or leave off --llm to get the plain, non-AI version instead.