CLI Reference¶

hachimoku provides two command names: 8moku and hachimoku. Both execute the same functionality.

Review Command (Default)¶

Running with no arguments or with arguments performs a code review.

8moku [OPTIONS] [ARGS]

The input mode is automatically determined by the type of arguments:

No arguments: diff mode. Reviews the changes on the current branch. Must be run inside a Git repository.
Single positive integer: PR mode. Reviews the diff and metadata of the specified GitHub PR. Must be run inside a Git repository.
File path(s) (one or more): file mode. Reviews entire specified files. Supports glob patterns (*, ?, [) and directory specifications. Works outside of Git repositories.
--commit <ref>: commit mode. Reviews the diff from a specific commit to HEAD, or between two commits. Must be run inside a Git repository. Cannot be combined with positional arguments or --base-branch.

# diff mode
8moku

# PR mode
8moku 42

# file mode
8moku src/main.py
8moku src/**/*.py
8moku src/

# commit mode
8moku --commit abc123
8moku --commit abc123..def456
8moku --commit HEAD~3

Review Options ¶

Options for the review command. These override configuration file values.

Option	Type	Description
`--model TEXT`	str	LLM model name
`--timeout INTEGER`	int (min: 1)	Timeout in seconds
`--max-turns INTEGER`	int (min: 1)	Maximum number of agent turns
`--parallel / --no-parallel`	bool	Enable/disable parallel execution
`--base-branch TEXT`	str	Base branch for diff mode
`--format FORMAT`	OutputFormat	Output format (`markdown` / `json`, default: `markdown`)
`--save-reviews / --no-save-reviews`	bool	Save review results
`--show-cost / --no-show-cost`	bool	Display cost information
`--max-files INTEGER`	int (min: 1)	Maximum number of files to review
`--ext TEXT`	str (repeatable)	Extension filter (file mode only, e.g. `--ext .py --ext .rst`)
`--commit TEXT`	str	Commit ref or range for commit mode (`SHA` or `SHA1..SHA2`)
`--issue INTEGER`	int (min: 1)	GitHub Issue number for context
`--no-confirm`	bool	Skip confirmation prompts
`--version`	-	Display version number and exit
`--help`	-	Display help

See Configuration for default values in the configuration file.

File Mode Behavior ¶

In file mode, the following processing is performed:

Expansion of glob patterns (*, ?, [)
Recursive file collection for directory specifications
Automatic exclusion of binary files (NULL byte detection in the first 8KB)
Symlink loop detection
Extension filtering via --ext option (all files included when not specified)
Results are a sorted, deduplicated list of absolute paths

When the number of files exceeds max_files_per_review (default: 100), a confirmation prompt is displayed. Use the --no-confirm option to skip the confirmation.

Creates default configuration files and agent definitions in the .hachimoku/ directory. Works both inside and outside Git repositories. Inside a Git repository, it also adds an entry to .gitignore.

8moku init [OPTIONS]

Option	Description
`--force`	Overwrite existing files with defaults
`--upgrade`	Update built-in agent definitions using hash comparison
`--help`	Display help

# Initial setup
8moku init

# Reset all files to defaults (including config.toml)
8moku init --force

# Update agent definitions after version upgrade (skip customized files)
8moku init --upgrade

# Force update all agent definitions including customized ones (config.toml preserved)
8moku init --upgrade --force

Flag behavior scope ¶

Target	`init`	`--force`	`--upgrade`	`--upgrade --force`
`config.toml`	Create	Overwrite	Not affected	Not affected
`agents/*.toml`	Create	Overwrite	Hash-based update	Force overwrite
`reviews/`	Create	Create	Not affected	Not affected
`.gitignore`	Add entry	Add entry	Not affected	Not affected

upgrade hash comparison ¶

--upgrade compares the SHA-256 hash of local files against built-in definitions and determines the action:

File does not exist: Add new file (Added)
Hash matches: Already up to date (Skipped (up to date))
Hash differs: Skip as customized (Skipped (customized))
Hash differs + --force: Force overwrite (Updated)

Created files (init / --force):

.hachimoku/config.toml - Configuration file (template with all options commented out)
.hachimoku/agents/*.toml - Copies of built-in agent definitions
.hachimoku/reviews/ - JSONL accumulation directory for review results
Automatic addition of /.hachimoku/ entry to .gitignore (Git repositories only; only if not already present)

agents ¶

Displays a list or details of agent definitions.

8moku agents [NAME]

Argument	Description
`NAME`	Agent name (omit for list view)

# List view
8moku agents

# Detail view
8moku agents code-reviewer

The list view displays NAME, MODEL, PHASE, and SCHEMA columns. Project-specific custom agents are marked with [custom].

config (Planned)¶

The configuration management subcommand is not yet implemented. Please edit .hachimoku/config.toml directly.

Output Streams ¶

hachimoku separates review reports from progress information in its output:

stdout: Review reports only. Supports pipes and redirects.
stderr: Progress information, logs, error messages, and confirmation prompts.

# Save report to file
8moku > review.md

# Pipe report to another command
8moku --format json | jq '.agents'

Exit Codes ¶

Code	Name	Meaning
0	SUCCESS	Normal completion. No issues found, or user confirmed an action
1	CRITICAL	Critical-level issues detected
2	IMPORTANT	Important-level issues detected (no Critical)
3	EXECUTION_ERROR	Runtime error (network, timeout, configuration parsing, etc.)
4	INPUT_ERROR	Input error (invalid arguments, Git requirements not met, file not found, permissions, configuration file issues)

Exit codes can be used for conditional branching in scripts and CI/CD pipelines:

8moku
case $? in
  0) echo "No issues found" ;;
  1) echo "Critical issues found" ;;
  2) echo "Important issues found" ;;
  3) echo "Execution error" ;;
  4) echo "Input error" ;;
esac