CLI Command Reference

Tip

This page is auto-generated from source code (commit 247afd5). Do not edit manually — run uv run python scripts/gen_docs.py to regenerate.

Note

This reference is generated from mutsumi --help output. Every option, argument, and default value matches the actual code. If something doesn’t match, the code is the source of truth.

mutsumi (TUI Launch)

Launch the Mutsumi TUI task board.

mutsumi [OPTIONS] [COMMAND]

Option	Short	Description	Default
--path PATH	-p	Path to task file (default: ./mutsumi.json, fallback: ./tasks.json)	—
--watch PATH	-w	Additional task file paths to watch (multi-project)	—
--version		Show version and exit	—
--help		Show help and exit	—

Examples

# Launch TUI (watches mutsumi.json in current directory)
mutsumi

# Watch a specific file
mutsumi --path /path/to/mutsumi.json

# Watch multiple files (multi-project)
mutsumi --path ~/proj-a/mutsumi.json -w ~/proj-b/mutsumi.json

# Print version
mutsumi --version

If this is your first launch, the onboarding wizard runs automatically. See Startup Flow for details.

---

mutsumi add

Create a new task and append it to mutsumi.json.

mutsumi add TITLE [OPTIONS]

Option	Short	Type	Values	Default
--priority	-P	choice	high, normal, low	normal
--scope	-s	choice	day, week, month, inbox	inbox
--tags	-t	text	—	—
--description	-d	text	—	—

Examples

# Minimal
mutsumi add "Fix login bug"

# Full options
mutsumi add "Fix login bug" -P high -s day -t "bugfix,urgent" -d "Session expires on refresh"

# Short flags
mutsumi add "Write tests" -P low -s week -t "dev"

A unique ID and created_at timestamp are auto-generated.

---

mutsumi list

List tasks from mutsumi.json.

mutsumi list [OPTIONS]

Option	Short	Type	Values	Default
--scope	-s	choice	day, week, month, inbox	—
--done / --no-done		flag	—	—

Examples

# List all tasks
mutsumi list

# Filter by scope
mutsumi list --scope day

# Only pending tasks
mutsumi list --no-done

# Only completed tasks
mutsumi list --done

---

mutsumi done

Mark a task as done (supports ID prefix matching).

mutsumi done TASK_ID

Argument	Description
TASK_ID	Full task ID or any unique prefix

Examples

# Full ID
mutsumi done 01JQ8X7K3M0000000000000001

# Prefix matching
mutsumi done 01JQ

# If prefix is ambiguous, Mutsumi lists matches
mutsumi done 01
# Error: Multiple tasks match '01'. Be more specific.

Sets status to "done" and auto-fills completed_at.

---

mutsumi edit

Edit an existing task’s fields (supports ID prefix matching).

mutsumi edit TASK_ID [OPTIONS]

Option	Short	Type	Values	Default
--title		text	—	—
--priority	-P	choice	high, normal, low	—
--scope	-s	choice	day, week, month, inbox	—
--tags	-t	text	—	—
--description	-d	text	—	—

Examples

# Change title
mutsumi edit 01JQ --title "New title"

# Change priority and scope
mutsumi edit 01JQ -P low -s week

# Replace tags
mutsumi edit 01JQ -t "docs,review"

# Update description
mutsumi edit 01JQ -d "Updated requirements"

---

mutsumi rm

Remove a task from mutsumi.json (supports ID prefix matching).

mutsumi rm TASK_ID

Argument	Description
TASK_ID	Full task ID or any unique prefix

Examples

mutsumi rm 01JQ

Removes the task and all its children.

---

mutsumi init

Generate a template mutsumi.json.

mutsumi init [OPTIONS]

Option	Description
--force	Overwrite existing file
--personal	Initialize personal task file (~/.mutsumi/mutsumi.json)
--project	Create mutsumi.json in cwd AND register as a project source

Examples

# Create mutsumi.json in current directory
mutsumi init

# Overwrite existing file
mutsumi init --force

# Initialize personal tasks
mutsumi init --personal

# Create and register as project
mutsumi init --project

Tip

In most cases you don’t need mutsumi init — running mutsumi for the first time triggers the onboarding wizard which handles file creation automatically.

---

mutsumi setup

Set up Mutsumi integration for an AI agent.

mutsumi setup [OPTIONS]

Option	Short	Type	Values	Default
--agent	-a	choice	claude-code, codex-cli, opencode, gemini-cli, aider, custom	—
--mode		choice	skills, skills+project-doc, snippet	skills

Modes

Mode	Behavior
skills	Remember preferred agent in config only. No files modified.
skills+project-doc	Save preference AND append integration instructions to the agent’s project doc (CLAUDE.md, AGENTS.md, etc.)
snippet	Print the integration prompt to stdout for manual pasting.

Examples

# List available agents and modes
mutsumi setup

# Skills-first (default -- no files modified)
mutsumi setup --agent claude-code

# Inject project doc into CLAUDE.md
mutsumi setup --agent claude-code --mode skills+project-doc

# Print prompt for manual use
mutsumi setup --agent custom --mode snippet

# Gemini CLI with project doc injection
mutsumi setup --agent gemini-cli --mode skills+project-doc

Running skills+project-doc again is safe — it detects existing sections and does not duplicate.

---

mutsumi migrate

Migrate from legacy file names and config locations.

mutsumi migrate [OPTIONS]

Option	Description
--config	Migrate config from ~/.config/mutsumi/ to ~/.mutsumi/
--all	Migrate both task file and config directory

Examples

# Migrate tasks.json -> mutsumi.json
mutsumi migrate

# Migrate config directory
mutsumi migrate --config

# Migrate everything
mutsumi migrate --all

---

mutsumi validate

Validate the task file schema.

mutsumi validate

Examples

# Validate default file
mutsumi validate

# Validate a specific file
mutsumi -p /path/to/mutsumi.json validate

---

mutsumi schema

Output the JSON Schema for mutsumi.json.

mutsumi schema

Examples

# Print schema to terminal
mutsumi schema

# Pipe to a file
mutsumi schema > schema.json

---

mutsumi project

Manage registered project sources.

mutsumi project

mutsumi project add

Register a project directory as a source.

mutsumi project add PATH [OPTIONS]

Option	Description
--name	Display name (default: directory name)

mutsumi project add .
mutsumi project add ~/projects/saas-app

mutsumi project remove

Unregister a project source.

mutsumi project remove NAME

Argument	Description
NAME	Project name

mutsumi project remove saas-app

mutsumi project list

List all registered projects with their paths.

mutsumi project list

---

ID Prefix Matching

Commands that take a TASK_ID argument (done, edit, rm) support prefix matching. You don’t need to type the full ID:

mutsumi done 01EX    # Matches if only one ID starts with "01EX"

If the prefix is ambiguous, Mutsumi lists matching tasks and asks you to be more specific.

---

Exit Codes

Code	Meaning
0	Success
1	General error (file not found, ambiguous ID, etc.)
2	Invalid arguments (click usage error)