cli-reference.md

CLI Reference

This page keeps the long command tables out of the root README.

productize onboard existing

Integrate Productize into a repository that already contains code and project knowledge.

productize onboard existing [path] [flags]

The command resolves the project root, inventories packages and existing documentation, generates canonical project knowledge, installs Productize for the selected agent, and registers the workspace. It is deterministic and does not invoke an AI model.

Flag	Default	Description
--agent, -a		Target one agent/editor name per occurrence; repeat the flag for several
--all-agents	false	Explicitly install into every supported agent/editor destination
--global, -g	false	Install skills in user scope instead of project scope
--copy	false	Copy installed assets instead of symlinking
--core-only	false	Install only core workflow skills
--no-tactical	false	Compatibility alias for --core-only
--skip-setup	false	Generate knowledge without installing agent assets
--skip-register	false	Do not start the daemon or register the workspace
--name		Display name used for first workspace registration
--exclude		Repository-relative scan exclusion; repeatable
--dry-run	false	Preview every step without mutations or daemon startup
--force	false	Replace unmarked canonical knowledge targets only
--yes, -y	false	Approve the complete non-interactive plan
--format	text	Output format: text or json

Results use ready, needs_review, or blocked. JSON output is versioned and includes root-resolution evidence, inventory coverage, per-step results, structured diagnostics, and exact next actions. Use productize init existing when only the generated knowledge needs to be refreshed.

Interactive onboarding selects one agent. --agent and --all-agents are mutually exclusive, and comma-separated agent lists are rejected. The combined plan and JSON setup.directory_summary report the exact unique agent skill directories and shared .productize metadata before application.

JSON uses schema_version: 1 with workspace_root, root_resolution, inventory, knowledge, setup, workspace_registration, diagnostics, and next_actions. Step statuses are planned, current, changed, skipped, needs_review, or failed. Exit code 0 means ready or a feasible dry-run; 1 means invalid selection, protection, or required review; 2 means an operational or output failure.

productize init existing

Adopt a mature repository into Productize project knowledge.

productize init existing [path] [flags]

The command deterministically scans repository facts and creates or refreshes durable context under .productize/project/. It does not invoke an AI model. Use it before creating PRDs, TechSpecs, or tasks in an existing codebase.

Flag	Default	Description
--dry-run	false	Preview generated project knowledge without writing files
--exclude		Repository-relative scan exclusion; repeatable
--force	false	Overwrite existing unmarked project knowledge files
--format	text	Output format: text or json

Generated or refreshed files:

• .productize/project/context.md
• .productize/project/conventions.md
• .productize/project/architecture.md
• .productize/project/decisions.md
• .productize/project/constraints.md

These five files are generated read models owned only when they carry the productize:project-knowledge marker. Keep human-authored additions in .productize/project/manual.md, which refresh never overwrites.

productize setup

Install Productize skills and reusable agents.

productize setup [flags]

Flag	Default	Description
--agent, -a		Target one agent name per occurrence; repeat for several
--skill, -s		Skill name to install, repeatable
--global, -g	false	Install to user directory instead of project
--copy	false	Copy files instead of symlinking
--list, -l	false	List setup assets without installing
--doctor	false	Inspect setup targets and drift without installing
--format	text	Output format for --doctor: text or json
--yes, -y	false	Skip confirmation prompts
--core-only	false	Install only core workflow, lifecycle, and gate skills
--no-tactical	false	Alias for --core-only
--all-agents	false	Explicitly install to every supported agent/editor destination
--all	false	Deprecated: setup installs all skills by default; also skips prompts

Non-interactive installs require an explicit target:

productize setup --agent opencode --yes
productize setup --all-agents --yes
productize setup --doctor --agent opencode --format json

Interactive setup uses a single-choice prompt. Exactly one detected agent is preselected; if several or none are detected, a choice is required with no default. --agent accepts one name per occurrence, cannot be combined with --all-agents, and never creates another agent's skill directory. OpenCode and Codex intentionally share .agents/skills; Claude Code uses .claude/skills. The confirmation summary lists every unique directory, overwrite count, install mode, skill count, and affected reusable-agent count.

Use --doctor to see the detected agents, selected targets, install paths, catalog path, stale or missing assets, and extension conflicts before changing anything.

productize setup cleanup

Remove old Productize-managed skill installations without touching the retained agent targets or shared .productize project state.

productize setup cleanup --keep-agent opencode --dry-run
productize setup cleanup --keep-agent opencode --yes
productize setup cleanup --keep-agent codex --keep-agent claude-code --yes

Flag	Default	Description
--keep-agent		Desired agent target to retain; repeatable
--global, -g	false	Clean user-scoped instead of project-scoped targets
--dry-run	false	Preview without filesystem mutations
--yes, -y	false	Skip the one cleanup confirmation
--format	text	Stable output format: text or json

Cleanup uses setup ownership metadata when available. Legacy paths are removable only when they are Productize symlinks to the expected canonical skill path or byte-identical copies of the current effective skill source. Drifted, unknown, and user-owned content is preserved and reported as needs_review. Cleanup never removes .productize/agents, the setup catalog, project knowledge, or workflows. JSON uses schema_version: 1; exit codes are 0 for clean/unchanged/feasible dry-run, 1 for invalid selection, cancellation, or review items, and 2 for filesystem or output failure.

productize upgrade

Upgrade Productize to the latest release.

productize upgrade

Package-manager installs print the command to run. Direct binary installs perform an in-place self-update.

productize migrate

Convert legacy XML-tagged artifacts to frontmatter.

productize migrate [flags]

Flag	Default	Description
--root-dir	.productize/tasks	Workflow root to scan recursively
--name		Restrict migration to one workflow name
--tasks-dir		Restrict migration to one task workflow directory
--reviews-dir		Restrict migration to one review round directory
--dry-run	false	Preview migrations without writing files

productize sync

Reconcile workflow artifacts into daemon state, then refresh canonical project knowledge from repository facts, ADRs, and durable shared workflow memory.

productize sync [flags]

Flag	Default	Description
--root-dir	.productize/tasks	Workflow root to scan
--name		Restrict sync to one workflow name
--tasks-dir		Restrict sync to one task workflow directory
--format	text	Output format: text or json

Text output reports project knowledge as current or degraded, followed by the source checksum and any updated, unchanged, skipped, or warning entries. JSON includes the optional project_knowledge object with updated, unchanged, skipped, warnings, source_checksum, degraded, inventory, diagnostics, and imported_repository_adrs. If refresh is degraded, resolve its warnings and run productize sync again to retry.

productize daemon

Manage the shared home-scoped daemon.

productize daemon start
productize daemon status
productize daemon stop [--force]

Use daemon start for explicit bootstrap, daemon status for health and transport info, and daemon stop for graceful shutdown. Most workflow commands auto-start the daemon.

productize workspaces

Manage daemon workspace registrations.

productize workspaces list [--format text|json]
productize workspaces show <id-or-path> [--format text|json]
productize workspaces register <path> [--name display-name] [--format text|json]
productize workspaces unregister <id-or-path> [--format text|json]
productize workspaces resolve <path> [--format text|json]

The daemon lazily registers workspaces on first use, but the workspaces family gives operators explicit control over the registry.

productize tasks validate

Validate task metadata before execution.

productize tasks validate [--name my-feature | --tasks-dir .productize/tasks/my-feature] [--format text|json]

Use tasks validate to check every task_*.md file in a workflow directory against the task metadata schema before tasks run.

productize tasks run

Start one daemon-backed workflow run.

productize tasks run <slug> [flags]

The CLI resolves workspace defaults locally, validates task metadata, auto-starts the daemon when needed, and starts the workflow through daemon transport. Concurrency defaults to one. --detach controls only whether the client follows the run; it does not change task scheduling or isolation.

Flag	Default	Description
--name		Workflow slug, defaults to positional slug
--concurrent	1	Maximum dependency-ready tasks to execute concurrently; must be positive
--include-completed	false	Re-run completed tasks
--format	text	Output contract: text, json, or raw-json
--skip-validation	false	Skip task metadata preflight; use only when validation already ran elsewhere
--force	false	Continue after task metadata validation fails in non-interactive mode
--attach	auto	Attach mode: auto, stream, or detach
--stream	false	Force textual stream attach mode
--detach	false	Start the run without attaching a client
--task-runtime		Per-task runtime override rule such as type=..., id=..., ide=..., model=...
--verify-command		Shell command used to verify integrated parallel task changes

Text mode preserves the human-readable run summary and watcher. JSON emits the lean workflow event stream as JSONL, while raw JSON emits full canonical event envelopes. A local parallel dry-run emits one schema-versioned plan object for both machine-readable formats.

Task batch size remains fixed at one. Parallel runs require a verification command unless Productize discovers a Make verify target, a Node verify or test script, a Go module, or a Rust workspace. Productize executes that command directly after every merged wave and once more before finalization, records its exit code and logs, and rejects verifier changes to the integration checkout.

Parallel mode requires a clean Git-root checkout. Each ready task runs in a Productize-owned worktree, successful branches merge deterministically, and the starting branch advances only by safe fast-forward. Failed task worktrees are retained; verified successful tasks are finalized so a rerun skips them. Parallel task runs reject --add-dir because shared external directories are not isolated by the repository worktrees. --dry-run --concurrent N performs only local read-only planning and does not start the daemon, create a run, worktree, branch, or repository file.

productize reviews

Inspect and remediate review workflows.

productize reviews fetch <slug> [--provider coderabbit --pr 42 --round N]
productize reviews list <slug>
productize reviews show <slug> [round]
productize reviews fix <slug> [flags]
productize reviews watch <slug> [flags]

reviews fetch imports provider feedback into .productize/tasks/<slug>/reviews-NNN/. reviews fix uses the same daemon-backed runtime model as tasks run, including --attach, --stream, and --detach; --ui remains a deprecated alias for --stream.

reviews watch waits for provider feedback, imports actionable rounds, starts child review-fix runs, and can optionally push committed fixes.

productize runs

Reattach, observe, and clean daemon-managed runs.

productize runs attach <run-id>
productize runs watch <run-id>
productize runs purge

Use runs attach or runs watch for textual streaming observation of an existing run. Use runs purge to delete terminal run artifacts according to the configured retention policy.

productize archive

Move fully completed workflows into the archive root, then refresh canonical project knowledge from both active and archived workflows.

productize archive [flags]

Flag	Default	Description
--root-dir	.productize/tasks	Workflow root to scan
--name		Restrict archiving to one workflow name
--tasks-dir		Restrict archiving to one task workflow directory
--format	text	Output format: text or json

Archiving can succeed while its derived project-knowledge refresh is degraded. The command reports the same text and JSON project-knowledge fields as productize sync; warnings are not silent, and the next sync is the repair path.

productize exec

Execute one ad hoc prompt.

productize exec [prompt] [flags]

Provide exactly one prompt source: a positional prompt, --prompt-file, or stdin.

productize exec is headless and ephemeral by default. Use --agent <name> to execute a reusable agent, --persist to create ~/.productize/runs/<run-id>/ for resumable sessions, --run-id to continue a persisted session, --format json for lean JSONL, and --format raw-json for the full raw event stream.

Flag	Default	Description
--ide	codex	Runtime: claude, codex, copilot, cursor-agent, droid, gemini, opencode, pi
--model	per IDE	Model override
--agent		Reusable agent to execute from .productize/agents/ or ~/.productize/agents/
--prompt-file		Read prompt text from a file
--format	text	Output contract: text, json, or raw-json
--reasoning-effort	medium	low, medium, high, xhigh
--access-mode	full	default or full runtime access policy
--timeout	10m	Activity timeout per job
--max-retries	2	Retry execution-stage ACP failures or timeouts N times
--retry-backoff-multiplier	1.5	Multiplier applied to the next timeout after each retry
--tail-lines	0	Maximum log lines retained per job; 0 means full history
--add-dir		Additional directories to allow, repeatable
--auto-commit	false	Include automatic commit instructions when the prompt asks for code changes
--extensions	false	Enable executable extensions for this exec run
--verbose	false	Emit operational runtime logs to stderr during exec
--tui	false	Deprecated compatibility flag; new exec runs remain headless
--persist	false	Persist exec artifacts under ~/.productize/runs/<run-id>/
--run-id		Resume a previously persisted exec session by run id
--dry-run	false	Preview prompts without executing

productize agents

Discover and inspect reusable agents.

productize agents list
productize agents inspect <name>

productize agents list prints resolved agents from workspace and global scope, then reports invalid definitions without hiding valid ones. productize agents inspect <name> prints source, runtime defaults, MCP summary, and validation status for one agent.

productize ext

Manage executable extensions.

productize ext <subcommand> [flags]

Subcommand	Description
ext list	List discovered extensions across all scopes
ext inspect <name>	Show manifest, capabilities, and enablement status
ext install <source>	Install from a local path or GitHub repo archive
ext uninstall <name>	Remove a user-scoped extension
ext enable <name>	Enable an extension on this machine
ext disable <name>	Disable an extension on this machine
ext doctor	Validate manifests and report health warnings

ext install accepts --yes / -y, --remote local|github, --ref, and --subdir.