Documentation / Reference

Command reference

Choose a command by the job you need done. See what it reads, what it writes, which flags it accepts and what to do next.

Syntax and examples are checked against the CLI’s v0.4.0 baseline. Known release limitations are called out below. Run stemma version and stemma <command> --help to check your installed binary.

For a complete task, start with provider migration guide or workflows and CI.

Source, enabled targets and this run#

The difference between source selection and output selection
Flag	Meaning	Where it works
`--from`	Where existing context comes from	import only; one source
`--targets`	Which providers the canonical project enables	import only; saved in project.json
`--target`	Which provider to process in this invocation	plan, apply, check, explain; not persisted
`--all`	Use the enabled project targets	plan, apply, check; does not mean every supported provider

Implemented identifiers: github-copilot, claude, codex and kiro. cursor is declared but unavailable. --target never adds a provider to project.json.

Shared options and paths#

--json selects machine-readable stdout on every command. A JSON report printed by plan --json is an envelope, not a replayable plan file.
--workspace DIRECTORY selects the repository root on every command except version. Default: the current directory, not an automatic search up to the Git root.
--help shows a command’s own flags. Put flags after the command name.
Plan and profile file arguments are relative to the selected workspace. Use forward slashes; traversal and symlinks are refused.
The examples use one command per line and work in a shell or PowerShell. TARGET, FILE and ENTITY_ID in syntax lines are placeholders.

One JSON document per invocation, with one exception

apply --all --json emits one JSON document per target (issue #10 ↗). For a consumer expecting one document, invoke apply --target TARGET --json --yes separately for each target.

stemma scan#

Find the agent configuration already present before choosing what to migrate.

stemma scan [DIRECTORY] [--json] [--workspace DIRECTORY]

Before you run it: An existing repository directory. No .stemma/ project is needed.
Files written: Nothing. Classifies file paths without reading their contents.
Result: Detected providers, configuration paths, confidence, skipped directories and scan limits.

shell

stemma scanstemma scan --workspace ../another-repo --json

Detection is not a validity check. Import parses the detected configuration.
Review any reported scan limit before trusting the inventory to be complete.

stemma import#

Bring one provider’s existing context into .stemma/ so it can be compiled for another provider.

stemma import [DIRECTORY] [--from SOURCE] [--targets TARGETS] [--name NAME] [--overwrite]

Before you run it: Configuration for an implemented source provider. Running init first is optional.
Files written: Canonical Markdown, project metadata, provenance and the manifest under .stemma/, in one transaction. Provider output is generated later by apply.
Result: A canonical project ready for validate and plan. Source files remain in place, and each one reproduced byte-for-byte is recorded as owned.

import flags and defaults
Flag	Behavior and default
`--from SOURCE`	auto (default), github-copilot, claude, codex or kiro. Auto refuses to choose when several providers are detected.
`--targets TARGETS`	Providers to enable in project.json. Comma-separated or repeatable. Default: only the imported provider. This selects future output; it does not generate it.
`--name NAME`	Project display name. Defaults to the repository directory name.
`--overwrite`	Replace a populated canonical project. This is not a merge: canonical edits can be replaced and obsolete Stemma entity files removed. When the project changes, STEMMA4303 identifies each destination and target whose ownership was revoked and not re-established by this import. Review and back up the project first.

shell

stemma import --from github-copilot --targets kiro# Or, in a separate migration, keep both providers enabled:# stemma import --from github-copilot --targets github-copilot,kiro

Import one source, then maintain the canonical Markdown. Re-importing is not the normal edit loop.
A populated project requires confirmation in an interactive terminal, or --overwrite in non-interactive use. There is no import --yes or import --all.
Ownership is recorded at import, so you can edit .stemma/ before the first apply back to the source provider. A source reported as STEMMA4302 was not reproduced byte-for-byte and stays a conflict that --adopt-untracked cannot lift.
Wrong-typed recognized metadata aborts the import with STEMMA1101 (STEMMA1501 for Kiro JSON agents), naming the key, the expected type and the type found. Nothing is written or replaced.
Replacing the project revokes previous target ownership before recording newly verified sources. Import warns with STEMMA4303; a later attempt to change a now-foreign destination is a STEMMA4301 conflict until you explicitly adopt it. An identical re-import preserves ownership, as do normal canonical edits followed by apply.

stemma init#

Start a canonical project when you want to author context yourself rather than import it.

stemma init [--name NAME] [--with-profiles]

Before you run it: A repository without an existing canonical project.
Files written: Initial project.json and provenance.json under .stemma/, plus optional default profiles.
Result: An empty project. Add targets to project.json and author Markdown entities before compiling.

init flags and defaults
Flag	Behavior and default
`--name NAME`	Project display name. Defaults to the directory name.
`--with-profiles`	Write default profiles for the implemented providers. Does not enable targets or create instructions.

shell

stemma init --name "Payments service" --with-profiles

Refuses to overwrite an existing canonical project. There is no init --targets flag.

stemma validate#

Check the canonical project, configured profiles and manifest before generating output.

stemma validate [--explain]

Before you run it: An imported or manually authored .stemma/ project.
Files written: Nothing.
Result: Entity counts and diagnostics. Errors fail validation; warnings alone do not.

validate flags and defaults
Flag	Behavior and default
`--explain`	Show diagnostic details and informational notes.

shell

stemma validate --explain

Does not establish that generated output is current. Use check for that.
Does not list every entity ID. Use plan --explain or plan --json to find IDs for explain.

stemma plan#

Preview the files a target would receive, their changes, and any adaptations or losses.

stemma plan (--target TARGETS | --all) [--profile FILE] [--explain] [--show-unchanged] [--output-plan FILE] [--adopt-untracked]

Before you run it: A canonical project and an explicit target selection.
Files written: Normally nothing. --output-plan writes the named JSON plan file, but does not apply provider output.
Result: File classifications, projection outcomes, diagnostics and approximate context estimates.

plan flags and defaults
Flag	Behavior and default
`--target TARGETS`	One or more providers, comma-separated or repeatable. Does not change project.json.
`--all`	Use only the targets enabled in project.json. Cannot be combined with --target.
`--profile FILE`	Use a repository-relative profile file. Its target must match. Otherwise loads .stemma/profiles/<target>.json, or an empty default if absent.
`--explain`	Include entity IDs, destinations, projection explanations and diagnostic details.
`--show-unchanged`	Include destinations whose bytes are already correct.
`--output-plan FILE`	Save one target’s plan for later replay. Use a dedicated repository-relative JSON path; saving can replace that file. This is not the same as --json.
`--adopt-untracked`	Classify foreign destinations as update rather than conflict, so the plan shows what adopting them would do. Applies to every foreign destination in the run, not one path. A plan without it classifies those files differently, so preview with the flag you intend to apply with.

shell

stemma plan --target kiro --explainstemma plan --target github-copilot --target kiro --show-unchanged

A plain plan does not save a snapshot. A later apply without --plan calculates a fresh plan.
A saved plan is replayed as an assertion, not as content: apply rebuilds from the current project and refuses unless the two agree. See Workflow and CI before using --output-plan.

stemma apply#

Generate provider files from the canonical project after reviewing a plan.

stemma apply (--target TARGETS | --all | --plan FILE) [--profile FILE] [--yes] [--adopt-untracked]

Before you run it: A canonical project with no blocking diagnostics for the selected target.
Files written: Selected provider files and the generation manifest. Writes are transactional per target; proposed provider-file deletions stay manual.
Result: Generated files and a manifest that records their hashes for later conflict checks.

apply flags and defaults
Flag	Behavior and default
`--target TARGETS`	One or more providers, comma-separated or repeatable.
`--all`	Apply the enabled project targets in sequence. Stops on the first failure; targets already applied are not rolled back as a group.
`--plan FILE`	Replay one saved plan. Use it on its own, without --all or --target. The plan is verified against a fresh rebuild, and the rebuild is what gets written.
`--profile FILE`	Use the same target-specific profile you reviewed with plan.
`--yes`	Authorize writes without an interactive prompt. Required for writes in CI or with --json. Does not waive conflicts or blocking diagnostics.
`--adopt-untracked`	Take ownership of foreign destinations and write them, for every such file in the run. It does not override a tracked file edited by hand, nor an imported source that failed STEMMA4302, and it is not a substitute for --yes.

shell

stemma plan --target kiro --explain# Review the plan before running the next command.stemma apply --target kiro --yes

An apply with unchanged files may still write the manifest to establish ownership. Before v0.4.0, ownership was established by apply rather than import; existing records from a successful apply remain usable.
Every plan diagnostic is retained in apply output, human and JSON, including when nothing needs writing and when the transaction fails. An interactive apply prints them before the confirmation prompt.
Two entities resolving to one destination are blocked with STEMMA6001 and exit code 6; no files are written.
A destination that lost ownership during project replacement is never rewritten silently: changing it requires explicit adoption, otherwise apply reports a conflict and exits with code 1.

stemma check#

Fail a local check or CI job when generated files are missing, changed or in conflict.

stemma check (--target TARGET | --all) [--warnings-as-errors]

Before you run it: A canonical project and generated files committed or present in the workspace.
Files written: Nothing. Reports problems without regenerating files.
Result: Per-target freshness, missing or stale paths, conflicts, diagnostics and a process exit code.

check flags and defaults
Flag	Behavior and default
`--target TARGET`	One provider. Unlike plan and apply, check does not accept repeated or comma-separated targets.
`--all`	Check every target enabled in project.json. Choose either --all or --target.
`--warnings-as-errors`	Also return a failure when warnings remain. Does not rewrite the diagnostics or accept losses for you.

shell

stemma check --target kirostemma check --all --warnings-as-errors

Loads profiles from .stemma/profiles/<target>.json. There is no check --profile or check --budget flag.
Issue #5 tracks a gap: delete-proposed files may not fail check and can be forgotten after apply. Review file retirement manually; a green check does not cover this case yet.

stemma explain#

Understand how one canonical entity reaches a target and why it is exact, adapted, lossy, blocked or skipped.

stemma explain ENTITY_ID --target TARGET [--profile FILE]

Before you run it: A canonical entity ID, found in plan --explain or in the JSON mappings.
Files written: Nothing.
Result: Source provenance, activation, profile changes, destination, outcome, explanation and estimated tokens.

explain flags and defaults
Flag	Behavior and default
`--target TARGET`	One provider to explain. Required; --all is not supported.
`--profile FILE`	Explain the entity using this target-specific profile instead of the default.

shell

stemma plan --target kiro --explain# Replace the ID below with one from your plan.stemma explain context.api-layer-conventions --target kiro

ENTITY_ID is an ID such as context.architecture, not a file path. There is no --why-not flag yet.

stemma version#

Identify the installed build and its schema and provider compatibility baseline.

stemma version [--json]

Before you run it: An installed Stemma binary. No repository is needed.
Files written: Nothing.
Result: CLI and schema versions, platform, importer version and declared targets with availability.

shell

stemma versionstemma version --json

Does not accept --workspace. Does not contact a server, check for updates or install an upgrade.

Find conflict recovery, exit codes and saved-plan requirements in Workflow and CI.

Source: CLI command handlers at v0.4.0 ↗. Follow open issues ↗ for behavior still being corrected.