Prompt management
Code-first prompt workflow — see Prompt management for concepts and Workflow for the end-to-end guide. Runningmoda prompts with no subcommand is equivalent to moda prompts status.
moda prompts init
Creates.moda/prompts.yml if absent (never overwrites). The default manifest is version 2: prompt_paths discovers prompts/**/*.prompt.{md,json,yaml,yml} (exact globs from the repository root), and an empty sources: [] list holds prompts mapped in code. See Workflow.
Paths are resolved against the current working directory, so run it from the project root. created distinguishes a fresh scaffold from an existing manifest, and manifestPath is the absolute path to verify — the agent envelope also lists it under artifacts.
Output
write_failed-style error rather than reporting status: "ok".
moda prompts status / moda prompts diff
Local-only comparison of discovered prompt files against.moda/prompts.lock.json. No network call. status lists every prompt; diff lists only the prompts that are changed, new, or deleted (plus an unchanged count). Neither is a textual diff: the lockfile stores content hashes only. Per-prompt state is new, changed, unchanged, or deleted.
Output (trimmed)
zeroMatchPatterns lists prompt_paths patterns that match no file. legacyOnlyFiles lists .prompt.* files that older CLIs discovered anywhere in the repository but the current exact globs miss. When either is non-empty the command adds a warning, pointing at moda prompts migrate for legacy-only files.
moda prompts migrate
Rewrites.moda/prompts.yml to version 2. It keeps every pattern, sources: entry, and comment, adds an explicit prompt_paths entry for each legacy-only file (so its key and lockfile entry are unchanged), and ensures a sources: list. The write is atomic, and a manifest that is already version 2 with nothing to add is left alone. Local-only.
The output lists
addedPaths, addedSources, zeroMatchPatterns (kept, reported for you to fix), and changed.
moda prompts sync
Uploads all discovered prompts (unchanged ones are server-side no-ops — versions are content-addressed and immutable), moves each prompt’scurrent pointer to the synced version, and writes .moda/prompts.lock.json.
Output (trimmed)
moda prompts promote
Moves a release label (dev, staging, prod) to a specific version. Returns the updated prompt with all versions.
A
dev promotion moves the same pointer that every sync overwrites, so it is replaced by the next moda prompts sync. Use staging/prod for stable release labels.Skills
Skill commands manage the SKILL.md files your coding agents use.moda skills push talks to the control plane using your API key; moda skills install runs offline.
moda skills install
Copies the integration guides bundled with the CLI into.claude/skills/<id>/ (and .cursor/rules/<id>.mdc when the project uses Cursor), so your own coding agent can follow them. Runs offline and never overwrites files Moda does not manage. --list prints every bundled guide.
moda skills install moda-cli installs or refreshes the CLI’s own moda-cli skill for every detected coding agent, the same step moda init runs, without the rest of the wizard. Run it after upgrading the CLI so the guide matches the new version. A copy you edited locally is kept and reported as kept.
moda skills push
Pushes local.claude/skills/**/SKILL.md files up to Moda. Files Moda manages (bundled guides installed with moda skills install, and the moda-cli skill) are skipped. --dry-run shows what would be pushed. moda skills sync and moda sync skills are legacy names for this command. A real sync also maintains a managed <!-- moda:fixes:begin --> block in the repo’s AGENTS.md that tells coding agents to propose and make fixes themselves from Moda’s evidence (moda investigate, moda problems, moda problems get <id> --evidence, moda traces get); only the fenced block is Moda-owned — the rest of the file is never touched, and --dry-run skips the write. If the markers are damaged (a begin marker without an end marker, an end without a begin, duplicated markers, or markers in reverse order), the file is left unchanged, agentsMd.status is skipped, and a warning explains how to repair the markers.
Harness
The harness commands produce and sync the cited map of your agent codebase. The supported path for analysis is the Moda GitHub App (see Harness); the CLI analyze path is experimental.moda harness analyze
Produces a cited harness report. Gated: without--experimental or MODA_HARNESS_ANALYZE_CLI=1 it prints a pointer to the GitHub App and exits 1.
Output (gated)
moda harness pull
Fetches a server-side analyze run (status while running, the report when done).--sync also syncs a passing report. --run-id targets a specific run; otherwise the run recorded in .moda/harness-remote-run.json is used.
moda harness validate-report / approve / sync
validate-report checks .moda/harness-report.json citations. approve --yes validates and writes a hash-bound approval file; sync --from-report uploads the approved report to Moda Cloud (it refuses unapproved reports) and writes .moda/sync-state.json. moda sync and moda sync harness are top-level aliases for harness sync; moda sync prompts aliases moda prompts sync.
moda harness scan / candidates / agents / explain
Local, no-LLM inspection commands:moda harness scan— discover local runtime agents and write.moda/harness.json(--jsonfor structured output).moda harness candidates— static candidate pre-pass with file:line citations (--out=PATH).moda harness agents— list detected runtime agents and families.moda harness explain [--agent=<id>]— explain the discovered harness graph.