Reference

Commands

Every agentic-fy CLI command. They all run in your terminal.

Global flags:

-v, --version — shows the logo, the version, and the list of commands.
--help — command help.
--no-color — disables colored output.

Most commands (except init and mcp) require an already-initialized project — an agentic-fy.config.yaml in the current directory or a directory above it.

init

agentic-fy init [path] [--tools <list>]

Creates the base project structure in path (default: current directory):

agentic-fy.config.yaml
agentic-fy/
├── specs/              (with .gitkeep)
├── changes/
│   └── archive/        (with .gitkeep)

Idempotent: running it again ensures the directories exist and does not overwrite the agentic-fy.config.yaml. It also configures the MCP integration for your AI tools.

Use --tools to skip the interactive prompt: --tools all, --tools none, or a comma-separated list such as --tools kiro,cursor. The mcp.json merge is non-destructive: an existing config keeps its other servers.

explore

agentic-fy explore

Thinking mode. Confirms an agentic-fy project exists and lists the active changes with their status. It doesn't create or change anything — it's a starting point to map the problem before proposing.

propose

agentic-fy propose <name>

Creates a change and drafts the artifacts from templates: proposal.md, design.md, tasks.md, and a spec delta at specs/<name>.delta.yaml. The <name> is normalized to a slug (e.g., "add login" becomes add-login). It does not overwrite existing files. At the end, it marks the change status as proposed.

apply

agentic-fy apply [name]

Reads the change's tasks.md, parses the checkboxes, and reports how many tasks are done and pending, listing the pending ones. Marks the status as applying. If name is omitted and there is exactly one active change, it is used; if there are several, the command asks you to specify the name.

verify

agentic-fy verify [name]

Checks whether the three artifacts (proposal, design, tasks) exist and whether all tasks in tasks.md are checked. It only marks the change as verified when everything is present and there are no pending tasks; otherwise, it points out what's missing.

merge

agentic-fy merge [name] [--dry-run]

Applies the change's spec deltas (specs/*.delta.yaml) into the project's consolidated specs at agentic-fy/specs/<capability>.md, keeping the change active (no archive). This "early-sync" keeps the specs — and the context an AI agent reads — current while the change is still in progress. It uses the same idempotent, fail-loud merge engine as archive. Use --dry-run to preview without writing.

list

agentic-fy list [--specs] [--long] [--json]

Lists the active changes. Use --specs to list the project specs instead, --long to include the title and task progress, and --json for machine-readable output.

show

agentic-fy show <name> [--artifact <id>] [--spec <id>] [--json]

Shows a change summary (status, title, artifacts, tasks). Use --artifact proposal|design|tasks to print a raw artifact, or --spec <id> to print a project spec. Suggests close names ("did you mean?") when the name doesn't match.

validate

agentic-fy validate [name] [--all] [--strict] [--json]

Validates a change's artifacts: missing artifact, untouched template, empty body, and tasks.md without a real checkbox. It also validates each spec delta (specs/*.delta.yaml): malformed YAML or an invalid structure is a hard error, an untouched delta template is a warning. Use --all to validate every active change and --strict to treat warnings as failures.

status

agentic-fy status [--json]

Overview of the active changes by stage, with task progress and any validation issues.

doctor

agentic-fy doctor [--json]

Checks project integrity: valid config, intact change metadata, orphaned directories, and consistent artifacts. Read-only — it does not repair anything.

context

agentic-fy context [--json]

Gathers the project context (config, active changes, and specs) into a single brief for the agent.

config

agentic-fy config show [--json]
agentic-fy config set <key> <value>

Reads and edits agentic-fy.config.yaml. Editable keys: version and schema. Every write is validated against the schema before saving.

completion

agentic-fy completion [shell]

Prints an autocompletion script for powershell, bash, or zsh. It does not install anything automatically — pipe it into your shell config as you prefer.

view

agentic-fy view [--static] [--json]

A dashboard of specs and changes, with a summary line (Changes · Merged · Specs · Tasks) and a task-progress bar. In an interactive terminal it opens a number-navigable view; --static prints the panel and exits, and --json returns the raw data.

mcp

agentic-fy mcp

Starts the MCP (Model Context Protocol) server over stdio, exposing the workflow commands as tools an AI agent can consume. Registered tools: explore, propose, apply, verify, merge, archive, list, show, validate, status, and context.

Connect to Kiro

The easiest way is to let agentic-fy init --tools kiro configure it for you. To do it manually, create (or edit) Kiro's MCP configuration file:

Workspace (this project only): .kiro/settings/mcp.json
User (all projects): ~/.kiro/settings/mcp.json

{
  "mcpServers": {
    "agentic-fy": {
      "command": "npx",
      "args": ["-y", "@agentic-fy/agentic-fy", "mcp"],
      "disabled": false,
      "autoApprove": ["explore", "list", "show", "validate"]
    }
  }
}

If agentic-fy is installed globally, you can use the binary directly:

{
  "mcpServers": {
    "agentic-fy": {
      "command": "agentic-fy",
      "args": ["mcp"],
      "disabled": false,
      "autoApprove": ["explore", "list", "show", "validate"]
    }
  }
}

autoApprove lets the read-only tools run without confirmation; the ones that write (propose, apply, archive) still ask for approval.

Connect to other editors

VS Code-based editors with MCP support use the same format, changing the file:

Cursor: .cursor/mcp.json
GitHub Copilot (VS Code): .vscode/mcp.json (uses the servers key instead of mcpServers)
Claude Code: .mcp.json
Windsurf: .windsurf/mcp.json

Getting Started → Concepts →