CLI Commands & Usage
Relevant source files
The following files were used as context for generating this wiki page:
The omp CLI serves as the primary interface for the Oh My Pi coding harness. It facilitates interactive agent sessions, automated repository analysis, and maintenance tasks. The CLI architecture is built around a central entry point that dispatches requests to specialized command adapters, supporting multiple runtime modes including an interactive TUI, one-shot text output, and a JSONL-based RPC server.
Sources: packages/coding-agent/DEVELOPMENT.md:3-10, packages/coding-agent/DEVELOPMENT.md:35-44
CLI Architecture and Boot Flow
The CLI follows a structured boot sequence starting from the process arguments and ending in an AgentSession. The cli.ts module acts as the initial gatekeeper, handling worker-host dispatch and Bun version guarding.
The boot flow ensures that settings, model registries, and session options are resolved before the agent begins processing.
Sources: packages/coding-agent/DEVELOPMENT.md:23-33
Development and Maintenance Commands
The project includes various bun scripts for internal development, type checking, and asset generation.
| Task | Command | Description |
|---|---|---|
| Typecheck + Lint | bun run check | The primary gate for code quality. |
| Test Suite | bun run test | Executes package tests. |
| Build Binary | bun run build | Builds the dist/omp binary. |
| Tool Views | bun run gen:tool-views | Rebuilds React tool renderers for the web. |
| Docs Index | bun run gen:docs | Regenerates the internal docs:// index. |
Sources: packages/coding-agent/DEVELOPMENT.md:12-21
Interactive Mode Commands
Within the TUI (Interactive Mode), users can issue slash commands to manage session state, specifically for task tracking.
Todo Command (/todo)
The /todo command controller manages a list of tasks organized into phases. It uses fuzzy matching to identify tasks and phases from user input.
| Verb | Usage | Description |
|---|---|---|
edit | /todo edit | Opens the todo list in the system $EDITOR. |
append | /todo append [phase] <task> | Adds a new task to a specific or default phase. |
start | /todo start <task> | Marks a task as in_progress. |
done | /todo done [task] | Marks a task or phase as completed. |
export | /todo export [path] | Writes the todo list to a Markdown file. |
Sources: packages/coding-agent/src/modes/controllers/todo-command-controller.ts:10-22, packages/coding-agent/src/modes/controllers/todo-command-controller.ts:403-418
Repository Management Commands
Specialized scripts handle changelog management and repository initialization for AI agents.
Changelog Rewriting
The rewrite-changelog.ts script uses AI models to consolidate noisy developer notes into user-facing release notes.
- Dry Run:
bun scripts/rewrite-changelog.ts --dry-run - Check Mode:
bun scripts/rewrite-changelog.ts --check(Exits with 1 if changes are needed). - Model Selection:
--model <provider>/<model-id>(Defaults togoogle-vertex/gemini-3.5-flash).
Sources: scripts/rewrite-changelog.ts:25-30
Repository Initialization (init)
The init agent generate a AGENTS.md file (titled "Repository Guidelines") at the project root. This command launches multiple explore agents in parallel to scan core source, tests, and configs.
Sources: packages/coding-agent/src/prompts/agents/init.md:6-12, packages/coding-agent/src/prompts/agents/init.md:27-30
Execution Modes and Planning
The CLI supports a Plan Mode which enforces read-only behavior. In this mode, agents generate an execution spec at local://<slug>-plan.md before any changes are applied.
Plan Resolution
To exit plan mode and begin implementation, the resolve tool must be called with specific parameters:
action:"apply"extra.title: The<slug>used in the plan filename.
Sources: packages/coding-agent/src/prompts/system/plan-mode-active.md:1-8
Release Note Generation
The ci-release-notes.ts script aggregates package-level CHANGELOG.md files into a single release body. It resolves the version range between the last published release and the target tag.
| Argument | Description |
|---|---|
tag | The target version tag (e.g., v1.0.0). |
output | The destination file path (defaults to release-notes.md). |
Sources: scripts/ci-release-notes.ts:20-25, scripts/ci-release-notes.ts:167-175