Command reference

All examples below match the shipped binary. Run sethu <command> --help to confirm flags on any release. Run sethu capabilities first when a migration behaves oddly.

Key terms

Attempt selection. The --attempt flag that picks one migration attempt by ID or unique prefix. Example: --attempt a3f9 scopes changes to that attempt when several share a directory.

Scope. The --scope flag on init that restricts investigation to listed paths. Example: --scope src/search.rs keeps tracing inside that file.

Slug. A short readable key that names one mode or page. Example: the installer merges owned modes by this key instead of by path.

Fan-out. One shared component reaching several operations at once. Example: the old response component serves random, smart, and metadata search together.

Install and capture

install

Install the Bob pack into a consumer repository.

sethu install ./consumer

Flag	Meaning
--attempt <ID>	Select a migration attempt by ID or unique prefix

It creates the /api-upgrade command, the skill with its references, and the migrator mode under .bob/. It merges owned modes by slug, records owned file hashes in .sethu/installation.json, adds .sethu/ to .git/info/exclude, and writes a nextest profile into .config/nextest.toml. It never overwrites a user-edited owned file silently. See step 1 in the Immich walkthrough.

init

Start a migration from a pair of OpenAPI specs.

sethu init --repo ./consumer old.json new.json

Flag	Meaning
--attempt <ID>	Select a migration attempt by ID or unique prefix
--repo <PATH>	Consumer repository path, defaults to the current directory
--scope <PATH>	Restrict investigation to this path, repeatable
--list	List existing attempts for the spec pair instead of initialising

It runs the pinned Vimanam over the spec pair and stores the output unchanged as an immutable capture. It copies both specs into .sethu/pairs/. It binds the attempt to the consumer baseline commit and the declared scope. It resumes an existing attempt only on an exact match. See step 2 in the Immich walkthrough.

Understand

changes

List the changes that need investigating.

sethu changes
sethu changes --all
sethu changes --group 5
sethu changes --json

Flag	Meaning
--all	Include non-breaking changes, shown in a separate section
--attempt <ID>	Select a migration attempt by ID or unique prefix
--group <N>	Split output into groups of this size for parallel tracing
--json	Emit machine-readable output

Output lists each required change by ID, method, path, kind, and severity. Records group by shared origin, so one changed component reaching several operations reads as fan-out. See step 3 in the Immich walkthrough.

context

Show focused contract context for one change ID.

sethu context <change-id>
sethu context <change-id> --level schema
sethu context <change-id> --prepare 1

Flag	Meaning
--attempt <ID>	Select a migration attempt by ID or unique prefix
--level <LEVEL>	overview, endpoint (default), or schema detail
--prepare <GROUP>	Write context artifacts for a whole group under .sethu/

It returns the unmodified change record plus readable old and new endpoint detail through exact operation selection. Tracer agents read the prepared artifacts without running commands. See step 4 in the Immich walkthrough.

Account

record

Record one change outcome with its evidence.

sethu record <change-id> --outcome unaffected_in_application --evidence src/search.rs:42
sethu record <change-id> --outcome fixed_and_verified --evidence run:<run-id>/<check>
sethu record <change-id> --outcome decision_required --evidence docs/choice.md --note "Paging needs a product call"

Flag	Meaning
--attempt <ID>	Select a migration attempt by ID or unique prefix
--outcome <OUTCOME>	One of fixed_and_verified, unaffected_in_application, no_usage_found, decision_required, unresolved
--evidence <REF>	One evidence reference, repeatable
--note <TEXT>	Free-text note attached to the record

Re-recording replaces the current disposition and appends the old one to a per-ID history. A fixed_and_verified outcome needs a passing run on the current patched commit. See step 8 in the Immich walkthrough.

check

Report accounting completeness and upgrade readiness.

sethu check
sethu check --require-ready
sethu check --json

Flag	Meaning
--attempt <ID>	Select a migration attempt by ID or unique prefix
--require-ready	Fail unless every required change also stands resolved
--json	Emit machine-readable output

It recomputes the required set from the attempt capture and validates the ledger against it. It exits nonzero on an incomplete ledger. See step 9 in the Immich walkthrough.

Reproduce and verify

stub

Serve versioned fixtures for one spec version on 127.0.0.1.

sethu stub --version new
sethu stub --version old --port 8080 --scenarios ./scenarios

Flag	Meaning
--attempt <ID>	Select a migration attempt by ID or unique prefix
--version <VERSION>	old or new spec version to serve
--port <PORT>	TCP port to bind to, 0 means any free port
--scenarios <DIR>	Directory holding fixture scenarios

The walkthrough exercises this command through step 7. See the Immich walkthrough.

verify

Run checks against the stub and record the results.

sethu verify --freeze
sethu verify
sethu verify --check random-new --manifest ./verify-manifest.json

Flag	Meaning
--attempt <ID>	Select a migration attempt by ID or unique prefix
--freeze	Record the harness hash before repair starts
--manifest <PATH>	Path to the verification manifest
--check <NAME>	Run only these named checks, repeatable

It overlays a frozen test harness onto worktrees of the original and patched commits and runs each named check against its own stub instance. A regression check passes only when the test result and the stub trace agree. See steps 6 and 7 in the Immich walkthrough.

Explain and discover

report

Generate a migration report from validated state.

sethu report --out ./report
sethu report --out ./report --format md

Flag	Meaning
--attempt <ID>	Select a migration attempt by ID or unique prefix
--format <FORMAT>	md, html, or both (default)
--out <DIR>	Directory that receives the report

It covers provenance, tool versions, accounting and readiness, every required change with its evidence, and the remaining blockers. See step 10 in the Immich walkthrough.

scan

Walk a spec history and find candidate upgrade pairs.

sethu scan ./spec-repo --spec openapi.json
sethu scan ./spec-repo --spec openapi.json --tags 'v1.*'

Flag	Meaning
--attempt <ID>	Select a migration attempt by ID or unique prefix
--spec <PATH>	Path to the spec file inside the repository
--tags <PATTERN>	Tag pattern to walk, defaults to all tags

It walks release tags in version order, diffs adjacent spec pairs with Vimanam, and ranks them by demo value. Candidate pairs carry provenance and explicit limits. Ranking stays a heuristic. The walkthrough starts from a pair this command can find. See the Immich walkthrough.

capabilities

Report what Sethu can do in this environment.

sethu capabilities
sethu capabilities --json

Flag	Meaning
--attempt <ID>	Select a migration attempt by ID or unique prefix
--json	Emit machine-readable output

It reports the Sethu and pack versions, the Vimanam, git, and nextest versions found, and the status of every command. The skill consults it before invoking anything. Run this check before starting the walkthrough. See the Immich walkthrough.