Skip to main content

Prompt management

Code-first prompt workflow — see Prompt management for concepts and Workflow for the end-to-end guide. Running moda 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
If the manifest is not on disk after the run, the command exits non-zero with a 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’s current 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 (--json for 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.

moda harness delete

Permanently deletes a synced harness from Moda Cloud.