ax/USAGE.md

Axolotl Usage Reference

Commands

ax init [path]

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

ax add <title> [flags]

Flag	Description
--type	issue (default), note, user, namespace
--status	open (default), done
--prio	high, medium, low
--namespace	Namespace (default: current user)
--tag	Add tag (repeatable)
--due	Due date
--content	Body text
--rel	Relation type:id (repeatable)

ax update <id> [flags]

Flag	Description
--title	New title
--status	New status
--prio	New priority
--type	New type
--namespace	Transfer to namespace
--assignee	Assign to user
--due / --clear-due	Set or clear due date
--content	New body text
--tag / --tag-remove	Add or remove tag
--rel / --rel-remove	Add or remove relation type:id

ax show <id>

Display node details.

ax list [flags]

Flag	Description
--type	Filter by type
--status	Filter by status
--prio	Filter by priority
--namespace	Filter by namespace
--tag	Filter by tag (repeatable)
--assignee	Filter by assignee
--mention	Filter by mention

ax edit <id>

Open node content in $EDITOR.

ax del <id> [-f]

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

ax alias [name] [command]

ax alias                            # list all aliases
ax alias mywork "list --tag work"   # create/update alias
ax alias del mywork                 # delete alias

Built-in aliases: mine, due, inbox

Argument expansion: $me → current user, $@ → all args, $1/$2/… → positional

Relations

Type	Description
blocks	Prevents target from closing until this is done
subtask	Marks as subtask of target
related	General association
assignee	Assigns to a user (single-value)

ax update A --rel blocks:B          # A blocks B
ax update abc12 --assignee alice    # assign to alice

Tags and Properties

Tags follow the _key::value pattern for properties:

Property	Values
_type	issue, note, user, namespace
_status	open, done
_prio	high, medium, low

Mentions and Inbox

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

ax add "Review PR @alice"           # alice gets an inbox entry
ax inbox                            # your inbox
AX_USER=alice ax inbox              # alice's inbox

JSON Output

All commands support --json:

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

Configuration

ax searches upward from CWD for .axconfig, falling back to ~/.config/ax/config.json.

{
  "user": "alice",
  "aliases": [
    {"name": "mywork", "command": "list --namespace myproject", "description": "My tasks"}
  ]
}

Server Mode

ax can run as a shared HTTP JSON API server:

ax serve    # starts server on configured host:port (default: 0.0.0.0:7000)

The server exposes the same operations (add, list, show, update, delete) over HTTP. Clients connect by setting remote.host / remote.port in their config — the CLI then transparently routes calls to the server instead of a local database.

OIDC Authentication

The server supports OIDC for authentication. Configure in .axconfig:

{
  "serve": { "host": "0.0.0.0", "port": 7000 },
  "oidc": {
    "issuer": "https://your-idp.example.com",
    "client_id": "axolotl",
    "client_secret": "secret",
    "public_url": "https://ax.example.com",
    "user_claim": "preferred_username"
  }
}

Client login:

ax login    # opens browser for OIDC flow, saves session token

Without OIDC configured, the server accepts an X-Ax-User header for the username (development/trusted networks only).

Docker

docker run -v ./data:/data g.eliaskohout.de/eliaskohout/axolotl-server:latest

The image runs ax serve and exposes port 7000. Mount a volume at /data to persist the database.

Permission Model

Every node has per-node access control. Permissions are transitive via BFS from the requesting user's own node.

Level	Relation	Grants
1	can_read	Read / show / list
2	can_create_rel	Create relations pointing to this node
3	can_write	Update title, content, tags
4	has_ownership	Full control including delete and granting access

• Creators automatically get has_ownership on nodes they create.
• Namespace nodes own regular nodes within them; users own their namespaces.
• Deleting an owner cascades to all nodes it owns.
• User nodes and namespace nodes are globally readable.

# Grant bob read access to a node
ax update <bob-user-id> --rel can_read:<node-id>

# Grant bob write access
ax update <bob-user-id> --rel can_write:<node-id>

Environment Variables

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

Database Location

ax searches for .ax.db upward from CWD (like git finds .git), so commands work from any subdirectory.