# Initialize a new database
ax init .

# Create an issue
ax create "Implement feature X" --tag backend --prio high

# Create with relations
ax create "Fix bug in auth" --rel blocks:abc12

# List open issues
ax list --status open

# Show issue details
ax show abc12

# Update an issue
ax update abc12 --status done

# View your inbox
ax inbox

# Define an alias
ax alias mywork "list --namespace myproject --status open"

Commands

`ax init [path]`

Create a new .ax.db database in the specified directory (default: current).

`ax create <title> [flags]`

Create a new node.

Flag	Description
`--type`	Node type: `issue` (default), `note`, `user`, `namespace`
`--status`	Status: `open` (default), `done`
`--prio`	Priority: `high`, `medium`, `low`
`--namespace`	Namespace (default: current user)
`--tag`	Add tag (repeatable)
`--due`	Due date
`--content`	Content/body text
`--rel`	Add relation `type:id` (repeatable)

`ax update <id> [flags]`

Update a node.

Flag	Description
`--title`	New title
`--status`	New status
`--prio`	New priority
`--due`	New due date
`--clear-due`	Clear due date
`--content`	New content
`--tag`	Add tag (repeatable)
`--tag-remove`	Remove tag (repeatable)
`--rel`	Add relation `type:id` (repeatable)
`--rel-remove`	Remove relation `type:id` (repeatable)

`ax show <id>`

Display node details.

`ax list [flags]`

Query and list nodes.

Flag	Description
`--type`	Filter by type
`--status`	Filter by status
`--prio`	Filter by priority
`--namespace`	Filter by namespace
`--tag`	Filter by tag
`--inbox`	Filter by inbox user
`--assignee`	Filter by assignee

`ax edit <id>`

Open node content in $EDITOR.

`ax delete <id> [-f|--force]`

Delete a node. Prompts for confirmation unless --force.

`ax inbox`

Show issues in current user's inbox (from @mentions).

`ax alias [name] [command]`

Manage aliases.

ax alias myinbox "list --inbox me"
ax alias --list
ax alias myinbox  # show alias command

Relations

Relations connect nodes together:

Type	Direction	Behavior
`blocks`	issue → issue	Prevents closing until blocker is done
`subtask`	issue → issue	Shows as tree under parent
`related`	any ↔ any	Shown in related section
`assignee`	issue → user	Adds to user's inbox

# Create subtask
ax create "Write tests" --rel subtask:abc12

# Block an issue
ax create "Fix login" --rel blocks:def34

# Assign to user
ax update abc12 --rel assignee:alice

Tags and Properties

Tags are flexible labels. Tags with pattern _key::value are properties:

# Regular tag
ax create "Task" --tag backend

# Property tags (set via flags)
ax create "Task" --type issue --status open --prio high
# Equivalent to: --tag _type::issue --tag _status::open --tag _prio::high

Built-in properties:

Property	Values	Required
`_type`	`issue`, `note`, `user`, `namespace`	Yes (default: `issue`)
`_status`	`open`, `done`	No
`_prio`	`high`, `medium`, `low`	No
`_namespace`	any string	Yes (default: current user)
`_inbox`	username	No (auto-set from @mentions)

Mentions and Inbox

Use @username in title or content to automatically add to user's inbox:

ax create "Review PR @alice" --content "@bob please check"
# Both alice and bob get this in their inbox

View inbox:

ax inbox                          # your inbox
AX_USER=alice ax inbox            # alice's inbox

JSON Output

All commands support --json for machine-readable output:

ax list --status open --json
ax show abc12 --json

Example output:

{
  "id": "abc12",
  "title": "Implement feature",
  "content": "Description here",
  "created_at": "2026-03-25T10:00:00Z",
  "updated_at": "2026-03-25T10:00:00Z",
  "tags": ["_type::issue", "_status::open", "backend"],
  "relations": {
    "blocks": ["def34"]
  }
}

Database Location

ax searches for .ax.db in the current directory and parent directories, similar to how git finds .git. This allows you to run commands from any subdirectory.

Environment Variables

Variable	Description
`AX_USER`	Override current username
`EDITOR`	Editor for `ax edit` (default: `vi`)

License

MIT