docs: simplify README and extract full reference to USAGE.md
- Condensed README to quick overview (~40 lines) with key features - Added install instructions for Alpine, Arch, source, and Docker - Created USAGE.md with full command reference, server mode, OIDC, and permission model docs - New features documented: server mode, OIDC authentication, per-node permissions, multiplatform auto-builds Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
This commit is contained in:
194
USAGE.md
Normal file
194
USAGE.md
Normal file
@@ -0,0 +1,194 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user