Every command on one page.

skill-suitcase import --source "$SRC" --json

Inspects and summarizes a catalog without resolving live install paths. Checks skill-suitcase.yaml, the skills/<name>/SKILL.md layout, portability metadata, variants, assignments, compatibility, and manifest logical groups. Findings have warning or error levels; warnings preserve ok: true.

skill-suitcase validate --source "$SRC" --json
skill-suitcase validate --source "$SRC" --strict --json

Validates manifest structure and referenced catalog content. --strict also applies the Skillify authoring contract, honoring only valid reviewed validationPolicy.skillify.skip entries, and validates the upstream lock when the catalog has one.

skill-suitcase targets --source "$SRC" --json

Reports target IDs, assignments, adapter metadata, resolved paths, per-path existence, and safety classification without creating paths. Local overrides have higher priority than manifest assignments.

skill-suitcase plan --source "$SRC" --target codex --json

Resolves the selected assignment and emits each skill's action, variant, source path, relative destination, evidence, and any blocked reason. Flat targets use the skill name as the destination; categorized Hermes uses <category>/<skill>. It does not resolve target install paths, choose install modes, hash content, or read or write live targets. An assignment exposed through mixed flat and categorized paths requires an explicit path ID as --target.

skill-suitcase diff \
  --source "$SRC" \
  --target codex \
  --codex-home "$HOME/.codex" \
  --json

Compares catalog source with the live modeled target. File actions are create, update, unchanged, extra, missing, or blocked. Source-policy failures, blocked variants, and read-only targets are reported. diff does not run the Git source-hygiene check; pack, plan-lock creation, and apply enforce the untracked-source gate. Planned entries retain their relative destination.

skill-suitcase status --source "$SRC" --json
skill-suitcase status \
  --source "$SRC" \
  --target codex \
  --codex-home "$HOME/.codex" \
  --json

Classifies planned installs using catalog content, live content, receipts, and install mode into current, missing, version, behind, dirty, blocked, or unknown. Each status entry includes its resolved relative destination. Those seven values are the complete status enum; see the safety model for their meanings and troubleshooting for responses. For upstream-managed skills, status may add lineage metadata.

skill-suitcase upstream check --source "$SRC" --json

Reports validated .skill-suitcase/upstream-lock.json declarations and imported lineage without fetching or writing anything.

skill-suitcase upstream fetch \
  --source "$SRC" \
  --skill existing-skill \
  --dry-run \
  --json

Fetches the declared upstream through its pinned provider into an isolated temporary workspace and home, then reports its diff from the catalog. It never writes the catalog or live agent homes. Git declarations pin a source tag or commit; skills.sh declarations pin the installer package version but not the referenced repository content revision.

skill-suitcase pack --source "$SRC" --target codex --dry-run --json

OUT="$(mktemp -d "${TMPDIR:-/tmp}/skill-suitcase-pack.XXXXXX")"
skill-suitcase pack \
  --source "$SRC" \
  --target codex \
  --codex-home "$HOME/.codex" \
  --output "$OUT" \
  --json

Dry-run reports the bundle plan. With --output, pack writes an immutable bundle below the explicit directory and returns its artifact manifest recording source provenance, selected skills, file hashes, planned target entries, relative destinations, and blocked entries. Staged files live under skills/<destination>/, and destination metadata participates in the artifact ID. It does not touch the live target.

Pack refuses output beneath an absolute resolved install root, including CLI target overrides, selected untracked non-ignored source files, sourcePolicy.deny matches, and provider-managed read-only targets. Always stage into a temporary directory outside both the catalog and every resolved target root; old artifact directories are not pruned automatically.

There is no CLI command that creates a plan lock. Library callers use buildPlanLock from the compiled dist/src/plan-lock.js module to create the deterministic calvinnwq.skills.plan-lock.v0 lock, write the JSON to an approved path, and pass it to apply --lock. assessPlanLock rebuilds current facts and returns drift reasons such as source_commit_changed or file_hashes_changed. Plan entries include relative destinations; legacy flat v0 entries without that field are treated as skill-name destinations. See the command reference for the worked example.

Apply with a staged artifact:

skill-suitcase apply \
  --source "$SRC" \
  --target codex \
  --codex-home "$HOME/.codex" \
  --artifact "/path/to/staged/skill-suitcase-bundle.json" \
  --json

Or apply with a plan lock and an explicitly approved symlink mode:

skill-suitcase apply \
  --source "$SRC" \
  --target codex \
  --codex-home "$HOME/.codex" \
  --lock "/path/to/plan-lock.json" \
  --mode symlink \
  --json

Requires exactly one approved input, a staged artifact or a plan lock, writes transactionally, and updates the target receipt with a record for every installed skill. Copy is the default mode; symlink mode links selected source paths inside the catalog source root. Lock mode reassesses the current plan and hashes against the lock; artifact mode rebuilds ordinary missing or behind writes from current catalog source and enforces artifact file hashes only for the dirty-behind exception. Categorized apply additionally refuses artifact_destination_mismatch when an artifact's destination differs from the current plan. Existing flat v0 artifacts without destination metadata use the skill name. Neither input binds path overrides, the resolved install root, or --mode.

Important refusals include stale or malformed approval input, blocked variants, unmanaged existing targets, unapproved dirty content, source-policy failures, read-only targets, and symlink source escapes and conflicts.

skill-suitcase track \
  --source "$SRC" \
  --target codex \
  --codex-home "$HOME/.codex" \
  --skill existing-skill \
  --json

Adopts an already-correct copy or symlink install by writing a receipt; it never rewrites skill files. Repeat --skill for targeted adoption or omit it for the all-planned-skills mode. Track has no dry-run flag; preview candidates with diff first.

skill-suitcase reconcile \
  --source "$SRC" \
  --target codex \
  --codex-home "$HOME/.codex" \
  --skill existing-skill \
  --dry-run \
  --json

After approval:

skill-suitcase reconcile \
  --source "$SRC" \
  --target codex \
  --codex-home "$HOME/.codex" \
  --skill existing-skill \
  --apply \
  --json

Replaces explicitly named receiptless mismatches from catalog source. Targets selected unknown catalog-planned skills; at least one repeatable --skill is required. Dry-run reports target and catalog differences plus the backup path. Apply preserves the prior target as rollback state, installs catalog source, writes a receipt, and verifies status.

skill-suitcase repair \
  --source "$SRC" \
  --target codex \
  --codex-home "$HOME/.codex" \
  --skill existing-skill \
  --dry-run \
  --json

After approval:

skill-suitcase repair \
  --source "$SRC" \
  --target codex \
  --codex-home "$HOME/.codex" \
  --skill existing-skill \
  --apply \
  --json

Restores explicitly named dirty, receipt-owned copy installs when catalog source should win. Dry-run reports the receipt, catalog, and live hashes, changed files, and the backup plan. Apply backs up live content, installs catalog source, refreshes the receipt, and verifies current status. Repair refuses unknown, missing, behind, symlink-mode, read-only, and unselected states rather than guessing intent.

skill-suitcase prune \
  --source "$SRC" \
  --target codex \
  --codex-home "$HOME/.codex" \
  --skill obsolete-skill \
  --dry-run \
  --json

After approval naming the target, skills, and plan ID:

skill-suitcase prune \
  --source "$SRC" \
  --target codex \
  --codex-home "$HOME/.codex" \
  --skill obsolete-skill \
  --plan-id <reviewed-plan-id> \
  --apply \
  --json

Removes explicit receipt-owned installs no longer assigned to the selected writable target. Dry-run returns a stable plan ID; apply requires the same skill list and exact plan ID, recomputes all state, quarantines physical directories into a plan-scoped root, removes exact verified symlinks, writes a transaction journal and receipt backup, and replaces the receipt atomically. Assigned, unreceipted, drifted, read-only, and path-escaping candidates are refused, as is a legacy .skills-sync.json receipt.

skill-suitcase rollback \
  --receipt "/path/to/target/.skill-suitcase-receipt.json" \
  --json

Reverses recorded apply, reconcile, or repair state after verifying that current target bytes still match the applied receipt; drift is a refusal. It removes a Suitcase-created symlink only when the link still matches its recorded source, and it does not restore promotions or arbitrary catalog edits. Categorized Hermes records use their nested target and destination while refusing category-parent symlinks or containment escapes.

skill-suitcase promote \
  --source "$SRC" \
  --target-skill "$HOME/.codex/skills/new-skill" \
  --dry-run \
  --json

After approval:

skill-suitcase promote \
  --source "$SRC" \
  --target-skill "$HOME/.codex/skills/new-skill" \
  --apply \
  --json

Moves a new target-created skill into catalog ownership. Apply copies the content, verifies hashes, replaces the original directory with a symlink to the catalog, and records the preserved backup path in its receipt. The promotion receipt is not executable by the current rollback command, which treats the symlink install as a safe no-op.

skill-suitcase import-target \
  --source "$SRC" \
  --target codex \
  --codex-home "$HOME/.codex" \
  --skill existing-skill \
  --dry-run \
  --json

After approval:

skill-suitcase import-target \
  --source "$SRC" \
  --target codex \
  --codex-home "$HOME/.codex" \
  --skill existing-skill \
  --apply \
  --json

Imports intentional edits to selected dirty, receipt-owned catalog skills back into the catalog. At least one repeatable --skill is required. Dry-run reports receipt, catalog, and target hashes plus planned repository writes. Apply copies target content into the catalog atomically, refreshes the receipt, and leaves normal Git changes for review.

skill-suitcase upstream import \
  --source "$SRC" \
  --skill existing-skill \
  --apply \
  --json

Repeats the pinned isolated fetch, refuses dirty selected catalog source, and writes only skills/<name> plus .skill-suitcase/upstream-lock.json. It never installs into a live target and never commits the resulting Git diff.