CLI Command Reference

Relevant source files

The following files were used as context for generating this wiki page:

• morty.sh
• cli/src/cli/args.ts
• cli/src/config/types.ts
• cli/src/config/loader.ts
• cli/src/config/writer.ts
• cli/src/cli/commands/init.ts
• README.md

Morty is an autonomous AI coding loop designed to execute AI agents on specific tasks until completion. It supports a wide variety of AI engines including Claude Code, OpenCode, Codex, Cursor, Qwen-Code, Factory Droid, and GitHub Copilot. The CLI provides two primary modes of operation: Single Task Mode (Brownfield), where a specific instruction is provided as a positional argument, and PRD Mode, where the tool iterates through a list of tasks defined in a Markdown, YAML, or GitHub Issues source.

Sources: morty.sh:1-10, cli/src/cli/args.ts:14-19, README.md:1-10

CLI Architecture and Execution Flow

The CLI is implemented in both a Bash script (morty.sh) and a TypeScript-based Node.js application. Both implementations share a common architecture for parsing arguments, loading configurations from the .morty/ directory, and managing the AI execution loop.

Command Execution Logic

When a command is issued, the system first parses the input to determine if it is a configuration command (like --init or --add-rule) or a task execution command. If a positional argument is provided, the system enters "Single Task Mode." Otherwise, it attempts to locate a task source such as PRD.md.

The diagram shows the high-level decision flow from user input to AI execution and final reporting.
Sources: morty.sh:1351-1400, cli/src/cli/args.ts:55-75

Primary Command Options

The Morty CLI supports extensive flags to customize the AI engine, workflow, and execution environment.

AI Engine Selection

Users can specify which AI CLI should be invoked to handle the coding tasks.

Flag	Engine	Description
--claude	Claude Code	Default engine; uses Anthropic's Claude Code CLI.
--opencode	OpenCode	Uses the OpenCode CLI.
--cursor	Cursor Agent	Uses the agent command from Cursor.
--codex	Codex	Uses the Codex CLI.
--qwen	Qwen-Code	Uses the Qwen-Code CLI.
--droid	Factory Droid	Uses the Factory Droid CLI.
--copilot	GitHub Copilot	Uses the GitHub Copilot CLI agents.

Sources: cli/src/cli/args.ts:28-35, README.md:73-81

Workflow and Execution Flags

These flags control how Morty interacts with the codebase and manages the project lifecycle.

Flag	Default	Description
--init	N/A	Initializes the .morty/ directory with config.yaml and progress.txt.
--no-tests	false	Skips writing and running tests during the task execution.
--no-lint	false	Skips the linting phase.
--fast	false	Shortcut to skip both tests and linting.
--parallel	false	Runs multiple tasks simultaneously using git worktrees.
--max-parallel	3	Defines the maximum number of concurrent agents.
--branch-per-task	false	Automatically creates a new git branch for every task.
--dry-run	false	Shows the intended prompt without executing the AI command.

Sources: cli/src/cli/args.ts:20-53, cli/src/config/types.ts:98-125, morty.sh:350-410

Project Configuration and Initialization

The --init command triggers a discovery process that creates a .morty/ configuration directory. This directory acts as the central hub for AI instructions and progress tracking.

Initialization Sequence

1. Detection: The system scans for package.json, pyproject.toml, go.mod, or Cargo.toml to identify the project language and framework.
2. Creation: It generates .morty/config.yaml with detected build/test/lint commands.
3. Progress Tracking: It initializes .morty/progress.txt to log completed and failed tasks.

The sequence diagram illustrates the internal process for bootstrapping a new project with Morty.
Sources: morty.sh:116-240, cli/src/cli/commands/init.ts:11-30, cli/src/config/writer.ts:68-96

Configuration Schema

The .morty/config.yaml file follows a structured schema (validated via Zod in the TypeScript implementation) to ensure the AI has sufficient context.

• Project: Includes name, language, framework, and description.
• Commands: Custom scripts for test, lint, and build.
• Rules: A list of global instructions the AI must follow (e.g., "Use TypeScript strict mode").
• Boundaries: Includes never_touch, a list of glob patterns for files the AI is prohibited from modifying.

Sources: cli/src/config/types.ts:6-38, cli/src/config/loader.ts:88-105

Task Sources and PRD Integration

Morty can ingest tasks from multiple formats, allowing it to act as an autonomous agent across different project management workflows.

• Markdown: Parses PRD.md (or a directory of .md files) for tasks formatted as - [ ] Task.
• YAML: Loads a structured list of tasks from a .yaml file, supporting parallel_group for ordering parallel execution.
• GitHub Issues: Uses the gh CLI to fetch open issues from a repository, optionally filtered by labels.

Sources: cli/src/cli/args.ts:80-97, morty.sh:455-550, README.md:95-125

Conclusion

The Morty CLI provides a robust interface for automating software development tasks by wrapping various AI engines in a controlled, git-aware environment. Through its configuration system in .morty/ and flexible task sourcing, it allows developers to delegate both single features and entire product requirement documents to autonomous agents while maintaining strict adherence to project rules and boundaries.

Sources: README.md:1-20, morty.sh:1480-1500