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]`
```bash
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) |

```bash
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:
```bash
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`:
```bash
ax list --status open --json
ax show abc12 --json
```

## Configuration

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

```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:

```bash
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`:

```json
{
  "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:
```bash
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

```bash
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.

```bash
# 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.