# bmo Command Reference
This file is a machine-readable reference for every bmo command. It is intended for AI agents,
scripts, and tools that need to understand the full CLI surface without running the binary.
All commands accept the global flags `--json` and `--db`. All enumerated values are
case-insensitive. Issue IDs may be supplied as bare integers (`1`) or in `BMO-N` format
(`BMO-1`).
## JSON Output Envelope
All commands that produce structured output use a consistent envelope when `--json` is passed.
Success:
```json
{"ok": true, "data": <payload>, "message": "<human summary>"}
```
Error:
```json
{"ok": false, "error": "<description>", "code": "<code>"}
```
Error codes:
| `general` | 1 | Unclassified error |
| `not-found` | 2 | Requested resource does not exist |
| `validation` | 3 | Invalid input |
| `conflict` | 4 | Operation would violate a constraint |
`--json` output is designed for programmatic consumption. The envelope shape and field names are
stable across patch releases within a major version.
## Enumerated Values
Valid values for status, priority, kind, and relation fields. All values are case-insensitive.
`in-progress` also accepts the aliases `in_progress` and `inprogress`.
| status | `backlog`, `todo`, `in-progress`, `review`, `done` |
| priority | `none`, `low`, `medium`, `high`, `critical` |
| kind | `bug`, `feature`, `task`, `epic`, `chore` |
| relation | `blocks`, `blocked-by`, `depends-on`, `dependency-of`, `relates-to`, `duplicates`, `duplicate-of` |
## Global Flags
These flags are accepted by every command.
| `--json` | bool | false | Output all results as JSON using the standard envelope |
| `--db <PATH>` | string | (auto-detected) | Override the database path. Also reads `BMO_DB` environment variable |
## bmo init
Initialize a new bmo project in the current directory.
**Synopsis:** `bmo init [--name <name>]`
Creates a `.bmo/` directory containing `issues.db` and `config.toml`. If the directory already
exists, the command is a no-op.
| `--name <name>` | string | (none) | Project name to store in config.toml |
**Example:**
```
bmo init --name my-project
```
**JSON output** (`data` field):
```json
{
"db_path": "/path/to/.bmo/issues.db",
"already_existed": false
}
```
## bmo config
Show or modify project configuration. When called without flags, prints all current config values.
**Synopsis:** `bmo config [--get <key>] [--set <key=value>]`
| `--get <key>` | string | (none) | Print the value of a single config key |
| `--set <key=value>` | string | (none) | Set a config key to a value (format: `key=value`) |
Supported config keys: `project_name`, `default_assignee`, `web_port`, `web_host`.
**Examples:**
```
bmo config
bmo config --get web_port
bmo config --set default_assignee=alice
```
**JSON output** (`data` field when listing all):
```json
{
"project_name": "my-project",
"default_assignee": null,
"web_port": 7777,
"web_host": "127.0.0.1"
}
```
## bmo version
Print the bmo version string.
**Synopsis:** `bmo version`
No flags beyond globals.
**Example:**
```
bmo version
```
**JSON output** (`data` field):
```json
{"version": "0.1.0"}
```
## bmo stats
Show issue statistics broken down by status, priority, and kind.
**Synopsis:** `bmo stats`
No flags beyond globals.
**Example:**
```
bmo stats
bmo stats --json
```
## bmo board
Show all issues organized into a Kanban board by status column.
**Synopsis:** `bmo board [--label <label>]... [--priority <priority>]... [--assignee <name>]`
| `-l, --label <label>` | string (repeatable) | (none) | Filter board to issues with this label |
| `-p, --priority <priority>` | string (repeatable) | (none) | Filter board to this priority |
| `-a, --assignee <name>` | string | (none) | Filter board to this assignee |
**Examples:**
```
bmo board
bmo board --assignee alice --json
bmo board --priority high --priority critical
```
**JSON output** (`data` field):
```json
{
"backlog": [ <issue>, ... ],
"todo": [ <issue>, ... ],
"in_progress": [ <issue>, ... ],
"review": [ <issue>, ... ],
"done": [ <issue>, ... ]
}
```
## bmo next
Show issues that are ready to work on — issues that have no unresolved blocking dependencies.
**Synopsis:** `bmo next [--assignee <name>] [--limit <n>]`
| `-a, --assignee <name>` | string | (none) | Restrict results to this assignee |
| `--limit <n>` | integer | 10 | Maximum number of results |
**Examples:**
```
bmo next
bmo next --assignee alice --limit 5 --json
```
**JSON output** (`data` field): array of issue objects.
## bmo plan
Show a phased execution plan derived from issue dependency relationships. Issues are grouped into
phases where each phase contains issues that can be worked in parallel.
**Synopsis:** `bmo plan [--assignee <name>] [--phase <n>]`
| `-a, --assignee <name>` | string | (none) | Filter plan to this assignee |
| `--phase <n>` | integer | (none) | Return only the issues in phase N as a flat array |
When `--phase` is given, the `data` field is a plain array of issue objects (not the full plan
envelope), suitable for a coordinator to iterate and dispatch. An out-of-range phase number
returns a `validation` error (exit 3).
When `--assignee` and `--phase` are both given, phase N is extracted from the full plan first,
then the result is filtered by assignee within that phase. An empty result is not an error.
`--assignee` requires `--phase`; using `--assignee` without `--phase` is a validation error (exit 3).
**Examples:**
```
bmo plan --json
bmo plan --phase 1 --json
bmo plan --phase 2 --assignee alice --json
```
**JSON output** (`data` field, without `--phase`):
```json
{
"total_issues": 12,
"total_phases": 3,
"max_parallelism": 4,
"phases": [
{"number": 1, "issues": [ <issue>, ... ]},
...
]
}
```
**JSON output** (with `--phase N`):
```json
{
"ok": true,
"data": [
{"id": 3, "title": "...", "status": "todo", ...},
{"id": 5, "title": "...", "status": "todo", ...}
],
"message": "Phase 1: 2 issue(s)."
}
```
Out-of-range phase error (exit 3):
```json
{"ok": false, "code": "validation", "error": "phase 5 does not exist (plan has 3 phases)"}
```
## bmo export
Export all issues, comments, labels, relations, activity, and file attachments to JSON.
**Synopsis:** `bmo export [--output <file>]`
| `-o, --output <file>` | string | (stdout) | Write output to this file path instead of stdout |
`--json` has no effect on this command; the output is always a JSON export bundle.
**Example:**
```
bmo export --output backup.json
bmo export > backup.json
```
## bmo import
Import issues from a JSON export file.
**Synopsis:** `bmo import <file> [--from-docket]`
| `<file>` | positional | (required) | Path to the JSON export file |
| `--from-docket` | bool | false | Treat the file as a docket-format export; remaps `DKT-` IDs to `BMO-` |
**Examples:**
```
bmo import backup.json
bmo import docket-export.json --from-docket --json
```
**JSON output** (`data` field):
```json
{"issues": 10, "comments": 3}
```
The envelope also includes a top-level `"warnings"` array listing any records that were skipped
due to unresolvable IDs.
## bmo truncate
Delete issues in bulk. Defaults to deleting all `done` issues if no filter is specified.
**Synopsis:** `bmo truncate [--status <status>]... [--all] [--yes]`
| `-s, --status <status>` | string (repeatable) | `done` | Delete issues with this status (repeatable for multiple) |
| `--all` | bool | false | Delete ALL issues regardless of status (mutually exclusive with `--status`) |
| `--yes` | bool | false | Skip the confirmation prompt |
Prompts for confirmation before deleting unless `--yes` is passed. Reports the count of deleted issues.
**Examples:**
```
bmo truncate
bmo truncate --yes
bmo truncate --status backlog --status todo
bmo truncate --all --yes
```
**JSON output**:
```json
{"ok": true, "data": {"deleted": 47}, "message": "Deleted 47 issue(s)."}
{"ok": true, "data": {"deleted": 0}, "message": "Nothing to delete."}
```
## bmo web
Start the local read-only web UI for browsing issues in a browser.
**Synopsis:** `bmo web [--port <port>] [--host <host>] [--no-open]`
| `-p, --port <port>` | integer | 7777 | TCP port to listen on |
| `--host <host>` | string | `127.0.0.1` | Host address to bind to |
| `--no-open` | bool | false | Do not automatically open a browser window |
`--json` has no effect on this command.
**Examples:**
```
bmo web
bmo web --port 8080 --no-open
bmo web --host 0.0.0.0 --port 7777
```
## bmo issue
Manage issues. Issue subcommands can be invoked directly as `bmo <cmd>` (e.g., `bmo list`,
`bmo show BMO-1`) or with the explicit prefix `bmo issue <cmd>` — both forms are equivalent.
The `bmo issue` prefix is kept for backward compatibility.
### bmo issue create
Create a new issue.
**Synopsis:** `bmo create --title <title> [options]`
| `-t, --title <title>` | string | (required) | Issue title |
| `-d, --description <text>` | string | `""` | Issue description |
| `-s, --status <status>` | string | `backlog` | Initial status |
| `-p, --priority <priority>` | string | `medium` | Priority |
| `-k, --kind <kind>` | string | `task` | Issue kind/type |
| `-a, --assignee <name>` | string | (none) | Assignee |
| `--parent <id>` | string | (none) | Parent issue ID |
| `-l, --label <label>` | string (repeatable) | (none) | Label to apply (repeat for multiple) |
| `-f, --file <path>` | string (repeatable) | (none) | File path to attach (repeat for multiple) |
**Examples:**
```
bmo create --title "Fix login bug" --kind bug --priority high
bmo issue create --title "Fix login bug" --kind bug --priority high
bmo create -t "Add tests" -k task --parent BMO-1 --label testing
bmo create --title "Epic: v2 launch" --kind epic --json
```
**JSON output** (`data` field): a single issue object.
### bmo issue list
List issues with optional filters. Excludes done issues by default.
**Synopsis:** `bmo list [options]`
Aliases: `bmo ls`, `bmo issue list`, `bmo issue ls`
| `-s, --status <status>` | string (repeatable) | (none) | Filter by status |
| `-p, --priority <priority>` | string (repeatable) | (none) | Filter by priority |
| `-k, --kind <kind>` | string (repeatable) | (none) | Filter by kind |
| `--assignee <name>` | string | (none) | Filter by assignee |
| `-l, --label <label>` | string (repeatable) | (none) | Filter by label (AND semantics) |
| `--parent <id>` | string | (none) | Filter to children of this issue |
| `--search <text>` | string | (none) | Full-text search in title and description |
| `--limit <n>` | integer | 50 | Maximum number of results |
| `--sort <field>` | string | (none) | Sort field |
| `--include-done` | bool | false | Removes the default `status != done` exclusion; done issues are returned alongside active ones. All other filters (priority, kind, labels, etc.) remain active. Distinct from `--all` which short-circuits every predicate. |
| `-a, --all` | bool | false | Return all issues regardless of status or other filters (short-circuits all predicates) |
| `--oneline` | bool | false | Print one compact line per issue (ID, status, priority, kind, title) |
**Examples:**
```
bmo list
bmo issue list
bmo list --status in-progress --assignee alice
bmo list --kind bug --priority high --json
bmo list --all --json
bmo list --search "login" --limit 10
bmo list --include-done --priority high
```
**JSON output** (`data` field): array of issue objects.
### bmo issue show
Show full details for a single issue, including sub-issues, relations, comments, and labels.
**Synopsis:** `bmo show <id>`
| `<id>` | positional (required) | Issue ID (e.g. `1` or `BMO-1`) |
**Examples:**
```
bmo show BMO-5
bmo show 5 --json
```
**JSON output** (`data` field):
```json
{
"issue": <issue object>,
"sub_issues": [ <issue>, ... ],
"relations": [ <relation>, ... ],
"comments": [ <comment>, ... ],
"labels": [ <label>, ... ]
}
```
### bmo issue edit
Edit one or more fields on an existing issue. Only the fields you supply are updated.
**Synopsis:** `bmo edit <id> [options]`
| `<id>` | positional (required) | | Issue ID |
| `-t, --title <title>` | string | (unchanged) | New title |
| `-d, --description <text>` | string | (unchanged) | New description |
| `-s, --status <status>` | string | (unchanged) | New status |
| `-p, --priority <priority>` | string | (unchanged) | New priority |
| `-k, --kind <kind>` | string | (unchanged) | New kind |
| `-a, --assignee <name>` | string | (unchanged) | New assignee |
| `--parent <id>` | string | (unchanged) | New parent issue ID |
**Examples:**
```
bmo edit BMO-3 --status in-progress
bmo edit 7 --title "Updated title" --priority high --json
bmo edit BMO-10 --assignee bob --parent BMO-1
```
**JSON output** (`data` field): the updated issue object.
### bmo issue move
Change an issue's status.
**Synopsis:** `bmo move <id> --status <status>`
| `<id>` | positional (required) | | Issue ID |
| `-s, --status <status>` | string | (required) | Target status |
**Examples:**
```
bmo move BMO-4 --status in-progress
bmo move 4 --status review --json
```
**JSON output** (`data` field): the updated issue object.
### bmo issue close
Mark an issue as done (sets status to `done`).
**Synopsis:** `bmo close <id>`
| `<id>` | positional (required) | Issue ID |
**Example:**
```
bmo close BMO-5
bmo close 5 --json
```
**JSON output** (`data` field): the updated issue object.
### bmo issue reopen
Reopen a closed issue (sets status to `todo`).
**Synopsis:** `bmo reopen <id>`
| `<id>` | positional (required) | Issue ID |
**Example:**
```
bmo reopen BMO-5
```
**JSON output** (`data` field): the updated issue object.
### bmo issue claim
Atomically claim an issue: sets status to `in-progress` and optionally records an assignee
in a single conditional SQL UPDATE. If another agent has already claimed the ticket, returns
a `conflict` error rather than overwriting.
**Synopsis:** `bmo claim <id> [--assignee <name>]`
| `<id>` | positional (required) | | Issue ID |
| `-a, --assignee <name>` | string | (none) | Assignee name to record |
**Exit codes:**
| `0` | Claimed successfully |
| `2` | Issue not found |
| `4` | Issue is already in-progress (conflict) |
**Examples:**
```
bmo claim BMO-7
bmo claim BMO-7 --assignee alice --json
```
**JSON output (`data` field):** the updated issue object.
When the claimed issue shares file attachments with another in-progress issue, the response
includes a top-level `"file_conflicts"` key (alongside `ok`, `data`, `message`):
```json
{"ok": true, "data": <issue>, "message": "Claimed BMO-7.", "file_conflicts": [...]}
```
### bmo issue delete
Permanently delete an issue. Prompts for confirmation unless `--yes` is passed.
**Synopsis:** `bmo delete <id> [--yes]`
| `<id>` | positional (required) | | Issue ID |
| `--yes` | bool | false | Skip the confirmation prompt |
**Examples:**
```
bmo delete BMO-9
bmo delete 9 --yes --json
```
**JSON output** (`data` field): `null`.
### bmo issue log
Show the activity log for an issue.
**Synopsis:** `bmo log <id> [--limit <n>]`
| `<id>` | positional (required) | | Issue ID |
| `--limit <n>` | integer | 10 | Maximum number of log entries to show |
**Examples:**
```
bmo log BMO-3
bmo log 3 --limit 20 --json
```
**JSON output** (`data` field): array of activity entry objects.
### bmo issue graph
Show the blocking/blocked-by dependency graph for an issue.
**Synopsis:** `bmo graph <id>`
| `<id>` | positional (required) | Issue ID |
**Example:**
```
bmo graph BMO-1
bmo graph 1 --json
```
**JSON output** (`data` field):
```json
{
"issue": <issue object>,
"relations": [ <relation>, ... ]
}
```
### bmo issue comment add
Add a comment to an issue.
**Synopsis:** `bmo comment add <id> --body <text> [--author <name>]`
| `<id>` | positional (required) | | Issue ID |
| `-b, --body <text>` | string | (required) | Comment body |
| `-a, --author <name>` | string | (none) | Comment author name |
**Examples:**
```
bmo comment add BMO-3 --body "Investigating now"
bmo comment add 3 --body "Fixed in commit abc123" --author alice --json
```
**JSON output** (`data` field): the created comment object.
### bmo issue comment list
List all comments on an issue.
**Synopsis:** `bmo comment list <id>`
| `<id>` | positional (required) | Issue ID |
**Example:**
```
bmo comment list BMO-3 --json
```
**JSON output** (`data` field): array of comment objects.
### bmo issue label add
Add a label to an issue. Creates the label if it does not already exist.
**Synopsis:** `bmo label add <id> <name> [--color <hex>]`
| `<id>` | positional (required) | | Issue ID |
| `<name>` | positional (required) | | Label name |
| `--color <hex>` | string | (none) | Label color in hex format (e.g. `#ff0000`) |
**Examples:**
```
bmo label add BMO-2 bug
bmo label add BMO-2 urgent --color "#ff0000" --json
```
**JSON output** (`data` field): the label object.
### bmo issue label rm
Remove a label from an issue. The label itself is not deleted from the system.
**Synopsis:** `bmo label rm <id> <name>`
Alias: `bmo issue label remove`
| `<id>` | positional (required) | Issue ID |
| `<name>` | positional (required) | Label name |
**Example:**
```
bmo label rm BMO-2 bug
```
**JSON output** (`data` field): `null`.
### bmo issue label list
List all labels attached to an issue.
**Synopsis:** `bmo label list <id>`
| `<id>` | positional (required) | Issue ID |
**Example:**
```
bmo label list BMO-2 --json
```
**JSON output** (`data` field): array of label objects.
### bmo issue label delete
Delete a label from the system entirely, removing it from all issues.
**Synopsis:** `bmo label delete <name>`
| `<name>` | positional (required) | Label name |
**Example:**
```
bmo label delete obsolete-label
```
**JSON output** (`data` field): `null`.
### bmo issue link add
Add a directional relationship between two issues.
**Synopsis:** `bmo link add <from-id> <relation> <to-id>`
| `<from-id>` | positional (required) | Source issue ID |
| `<relation>` | positional (required) | Relation kind (see enumerated values above) |
| `<to-id>` | positional (required) | Target issue ID |
**Examples:**
```
bmo link add BMO-1 blocks BMO-2
bmo link add 3 depends-on 1 --json
```
**JSON output** (`data` field): the created relation object.
### bmo issue link remove
Remove a relation by its numeric relation ID (not an issue ID).
**Synopsis:** `bmo link remove <relation-id>`
| `<relation-id>` | positional (required) | Numeric relation ID (obtain from `bmo issue link list`) |
**Example:**
```
bmo link remove 7
```
**JSON output** (`data` field): `null`.
### bmo issue link list
List all relations for an issue.
**Synopsis:** `bmo link list <id>`
| `<id>` | positional (required) | Issue ID |
**Example:**
```
bmo link list BMO-1 --json
```
**JSON output** (`data` field): array of relation objects.
### bmo issue file add
Attach a file path to an issue.
**Synopsis:** `bmo file add <id> <path>`
| `<id>` | positional (required) | Issue ID |
| `<path>` | positional (required) | File path to attach |
**Example:**
```
bmo file add BMO-3 src/main.rs
bmo file add 3 docs/spec.md --json
```
**JSON output** (`data` field): the created file attachment object.
### bmo issue file rm
Remove a file attachment from an issue.
**Synopsis:** `bmo file rm <id> <path>`
Alias: `bmo issue file remove`
| `<id>` | positional (required) | Issue ID |
| `<path>` | positional (required) | File path to remove |
**Example:**
```
bmo file rm BMO-3 src/main.rs
```
**JSON output** (`data` field): `null`.
### bmo issue file list
List all file attachments on an issue.
**Synopsis:** `bmo file list <id>`
| `<id>` | positional (required) | Issue ID |
**Example:**
```
bmo file list BMO-3 --json
```
**JSON output** (`data` field): array of file attachment objects.
### bmo issue file conflicts
Show file conflicts: other in-progress issues that share one or more file attachments with
the given issue.
**Synopsis:** `bmo file conflicts <id>`
| `<id>` | positional (required) | Issue ID |
Exit code is always `0` — conflict presence is information, not an error.
**Example:**
```
bmo file conflicts BMO-7
bmo file conflicts BMO-7 --json
```
**JSON output** (`data` field): array of conflict objects, empty array when no conflicts.
```json
[
{
"file": "src/auth.rs",
"conflicts_with": [
{"id": 12, "title": "Refactor auth middleware", "status": "in-progress"}
]
}
]
```