CLI

Install the CLI with npm install --global intentloom. The public package supports the intentloom binary only; programmatic imports and deep imports are not part of the public CLI contract. The current stable release is 1.0.2, served by the latest dist-tag; pin it with intentloom@1.0.2 when reproducibility is required.

See the release state for capability availability across the published package and current main.

Intentloom commands are local and deterministic. Generated files are Intentloom-owned only when recorded in the source map; the persisted ownership value remains aif-owned-generated for v0.1 compatibility. Project-owned files are never silently replaced.

init, adopt, plan, diff, sync, and doctor use the shared structural validator. Existing project metadata is parsed and validated before semantic ownership/filesystem checks. Generated config, manifest, source map, feature brief, and context pack structures are validated before output or writes. doctor aggregates config, manifest, source-map, Agent Skill, and semantic cross-document issues and never modifies files.

Inspect

intentloom inspect PROJECT_PATH|--root PATH reports bounded, read-only facts about one explicit project root. It detects the profile, known adapter instruction paths, and Intentloom metadata readiness. --json returns the versioned application result; human output is rendered from that same result.

Inspection does not execute scripts, invoke Git or package managers, install dependencies, access the network, read file contents other than bounded profile evidence, traverse ignored build/dependency trees, follow symbolic links, or write project files. Secret-like paths are excluded from the result. A symbolic link used as the requested root is rejected with exit code 3.

Harness inspect and replay

intentloom harness inspect --file SCORECARD.json [--root PATH] [--json] loads one explicitly supplied JSON scorecard and renders the canonical read-only inspection view. It exposes scenario/request identity, terminal status, score and assertion counts, bounded event/artifact counts, diagnostics, and whether replay is available; event payloads and artifact contents are not returned.

intentloom harness replay --file SCORECARD.json [--root PATH] [--mode simulate|strict] [--json] uses the same validated scorecard and deterministic replay operation. The default mode is simulate; strict also treats recorded errors as failed steps. Replay never repeats external effects. Both commands resolve --file within the supplied root, perform no writes, process execution, network access, or provider calls, and return exit code 3 for unreadable or invalid scorecards.

Timeline

intentloom timeline PROJECT_PATH|--root PATH [--case-id ID] collects bounded local Git commit evidence and renders a release-case timeline. The default case ID is release; --json returns the versioned timeline result. Timeline quality distinguishes complete, bounded, and unavailable evidence. It does not infer review, CI, approval, release conformance, or causality.

--adapters accepts a comma-separated selection of claude, codex, cursor, and copilot. Multi-adapter output is order-independent, identical shared files are emitted once, and non-identical destination collisions stop before writes. --profile controls documented path-scoped Cursor and Copilot derivatives.

Provider cache cleanup

intentloom clean --cache [PROJECT_PATH|--root PATH] [--provider github|gitlab] [--project-key KEY] [--json] removes only the local provider evidence cache at .aif/cache/providers/. With no provider or project key it purges the complete provider cache. --provider purges one provider, and --provider together with --project-key purges one provider/project scope. A project key without a provider is rejected with exit code 2.

The command does not read project metadata, use credentials, call the network, invoke subprocesses, or modify project-owned files. A missing cache is a successful no-op. Human and JSON output report the same relative cache path and scope; absolute paths and cache contents are never emitted.

Provider evidence import

intentloom evidence import --provider github|gitlab --file EXPORT.json --project-key KEY [--json] imports one explicitly supplied provider export. The payload is treated as untrusted, bounded input and is normalized without credentials, network calls, polling, subprocesses, or project writes. The caller-supplied project key isolates the result from other repositories; actor identities and arbitrary provider fields are not copied into evidence. Invalid files exit 3; bounded results remain usable and report diagnostics.

Adoption

intentloom adopt --dry-run returns the same deterministic adoption proposal in human or JSON form and creates no .aif, backup, or staging state. Proposal actions are create, map-existing-project-owned, map-existing-aif-compatible-document, generated-candidate, conflict, unsupported, skip, and manual-decision-required. Existing files are never claimed from their path, header, name, or content.

intentloom adopt without --dry-run accepts only a proposal with no manual decisions and routes safe generated creation through transactional sync. A blocked proposal writes nothing; a partial failure reports restored/incomplete status through the proposal's applicationStatus.

Use repeated --project-owned-mapping SOURCE=DESTINATION and --documentation-mapping SOURCE=DESTINATION options with adopt or init to record an explicit adoption resolution. In v0.1 both sides must be the same normalized project-relative path. The values are persisted in .aif/config.yaml; a project-owned mapping prevents ownership of that generated destination, and a documentation mapping chooses the authoritative existing document for an otherwise ambiguous concept.

Doctor

Doctor findings contain a stable code, error/warning/info severity, category, project-relative path, concise message, sorted remediation list, read-only guarantee, and related adapter/profile where applicable. Categories are config, schema, ownership, generated-file, adapter, profile, documentation, migration, security, and drift. Findings are sorted by code and path.

Doctor exits 0 when there are no error findings, including warning-only states; it exits 3 for one or more project validation errors and 2 for CLI invocation errors. It never uses transaction codes 4 or 5, writes files, creates .aif, repairs metadata, or refreshes stale output.

Transactional sync

intentloom sync consumes the structured transaction result directly. It does not infer success from filesystem presence, lack of an exception, or a subsequent empty diff. Human and JSON output use the same mapped outcome and exit code.

A successful write reports created, updated, and unchanged counts; manifest and source-map update status; consistency validation; and cleanup. A second identical sync reports Intentloom sync completed. No changes required.

intentloom sync --dry-run builds and reports the plan without executing the transaction. It does not create generated files, metadata, staging, or backup artifacts and prints Dry run — no files were changed. A conflict discovered during dry-run is still exit code 3.

Exit codes

The following values are a stable CLI contract and may be consumed by CI:

Code	Meaning
0	Successful command, successful sync, or successful no-op/dry-run plan.
2	CLI syntax/invocation error or missing required initialization input.
3	Conflict or pre-write validation failure; no transaction was applied.
4	Transaction failed and rollback completed; project state was restored.
5	Transaction failed and rollback was incomplete; inspect reported paths.

Incomplete rollback is never described as restored state. Output preserves the original failed stage and error code, adds transaction-rollback-incomplete, and lists only sorted project-relative paths requiring inspection.

JSON output

intentloom sync --json returns the same outcome as human mode with deterministic path arrays. Fields include status, dry-run status, failed stage, error code, rollback status and failures, created/updated/unchanged/conflict paths, metadata update flags, consistency validation, cleanup, and exit code. JSON and human modes never include generated contents, raw metadata, external absolute target paths, or exception stacks.

Artifact validation JSON uses artifact-validation-failed and a sorted errors array. Each error includes a stable code, structural/semantic phase, artifact type, schema id/version, project-relative document path, safe field path, and concise message. Project artifact validation exits 3 before a transaction. Doctor-only generated-state findings use the distinct urn:aif:semantic:generated-state:1 contract and identify the affected project-relative path; they are not mislabeled as schema failures for config, manifest, or source-map documents.

Adapter-specific findings include adapter-capability-experimental, adapter-capability-unsupported, adapter-profile-unsupported, adapter-output-stale, shared-file-conflict, path-scoped-rule-invalid, and stored-path-incompatible. Missing generated files identify the related adapter where the destination is unambiguous.