aven 0.1.2

Local-first task manager CLI and sync server
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153

# Aven CLI Primer

`aven` is a local-first task manager backed by SQLite. Use it to find work,
inspect tasks, update status, and leave durable handoff context.

## Start here

- Use `aven doctor` when the active workspace, database, or project routing is
  unclear.
- Run `aven skill install` when the aven skill should be installed into detected
  coding-agent skill directories. Use `--agent <claude|opencode|codex>` to
  choose explicit targets.
- Run `aven <command> --help` when you need flags not shown here.

## Task refs and values

- Use refs printed by command output, preferably qualified refs like `APP-7KQ9`.
- Do not mention task refs in commit messages, PR descriptions, or external
  systems. They identify the user's local tasks.
- The suffix is stable identity. The project prefix is display context and can
  change when a task moves projects.
- Bare suffix refs work when unambiguous.
- Typed suffix refs must be at least 3 characters.
- If `aven` reports `ambiguous-ref`, retry with a longer suffix.
- Status values are `inbox`, `backlog`, `todo`, `active`, `done`, and
  `canceled`.
- Priority values are `none`, `low`, `medium`, `high`, and `urgent`.
- Add `--workspace <name-or-key>` when a command must target a specific
  workspace.

## Core commands

```sh
aven list --project app
aven list --status todo
aven list --all
aven list --deleted
aven list --ready
aven list --blocked
aven search "auth bug"
aven context APP-7KQ9
aven show APP-7KQ9 --full
aven add "fix conflict display" --priority high --label bug
aven add "add due dates" --epic
aven epic add APP-7KQ9 APP-7KQ0
aven epic remove APP-7KQ9 APP-7KQ0
aven epic list APP-7KQ0
aven dep add APP-7KQ9 APP-7KQ0
aven dep remove APP-7KQ9 APP-7KQ0
aven dep list APP-7KQ9
aven update APP-7KQ9 --status active
aven update APP-7KQ9 --title "clearer title" --priority medium
aven project list --search app
aven label list --search bug
aven note APP-7KQ9 "durable handoff context"
aven delete APP-7KQ9
aven restore APP-7KQ9
```

- Use `aven <command> --help` to find maintenance commands for renaming,
  deletion, backup, export, import, and integrity checks.

- Use `show --full` before decisions that depend on description, labels, notes,
  deletion state, or conflicts.
- Use `context <ref>` when one task snapshot is needed before acting. It gathers
  task fields, description, labels, notes, dependencies, blockers, conflicts,
  deletion state, refs, and project metadata.
- Human-readable CLI output is the default agent-facing format. Use
  `context <ref> --json` only when a machine-readable snapshot is needed for a
  script, MCP server, bot, web UI, or other structured integration.
- After `aven add`, capture and report the printed ref so future agents can use
  it.
- When creating follow-up tasks from a discussion, investigation, review, or
  plan, include enough detail in the task description for the task to stand
  alone. Capture rationale, scope, acceptance criteria, implementation notes,
  and related tasks when useful. Use `--description-file` or
  `--description-stdin` for multi-paragraph descriptions.
- Add dependencies between related tasks when one task must finish before another
  can start. Use `dep add <blocked> <blocker>`.
- Use epics when one task is part of a larger body of work. Create an empty epic
  with `add --epic`, convert a task with `update <ref> --epic on`, and link
  children with `epic add <child> <epic>`.
- Epic membership does not make a child blocked. Do not use dependencies to model
  epic membership, and do not use epics to model ordering.
- Epics do not nest, and each child belongs to one epic. Work child tasks
  individually and mark the epic done when the larger outcome is complete.
- `list --ready` excludes epics so agents pick actionable child tasks.
- Let commands infer the project from the current directory, even if project
  does not exist yet. Pass `--project` only if project is specified by user.
- Use `project rename <old> <new> [--prefix <prefix>]` when a project itself
  has a wrong name or prefix. Use task updates only when moving tasks between
  distinct projects.
- Use `search <query>` when finding an unknown task by ref, title,
  description, project, label, note, status, or priority. Search includes done
  and canceled tasks in the active workspace.
- Use `list --deleted` with normal filters to list deleted tasks only.
- Use `list --all` with normal filters to include deleted tasks with live tasks.
- Use `search <query> --all` when deleted tasks should be included in broad
  search results. Ref-shaped search input can return a deleted task and prints
  deleted metadata when it does.
- Use `bulk-update --dry-run` before broad mutations.
- Use `list --ready` when selecting new work to avoid blocked or completed tasks.
- In `aven prime`, Active, Ready, and Blocked partition open issues by
  pickability. `blocked_by=[REFS]` lists unresolved blockers, and
  `blocks=[REFS]` lists open dependents. Run `aven show <ref> --full` for
  descriptions, notes, resolved dependencies, and conflicts.
- Inspect dependency context with `show <ref> --full` before changing task order or
  status. The `depends_on` and `blocks` sections show blockers and dependents.

## Structured output

- Human-readable output is the default and preferred for agent use.
- `--json` is available on `context`, `search`, `list`, `show`, `dep list`,
  `epic list`, `project list`, `label list`, `conflict list`, `conflict show`,
  `prime`, and `doctor`.
- JSON task objects include `is_epic`, `epic_parent`, and `epic_children`.
  Use these fields to distinguish epic membership from dependency ordering.
- Use `--limit <n>` with list-style reads such as `list`, `project list`,
  `label list`, `conflict list`, and `prime` to bound response size.

## Sync behavior

```sh
aven sync
aven daemon
aven daemon restart
```

- Sync output reports pushed and pulled counts, a cursor, and completion state.
- `aven daemon restart` restarts the macOS LaunchAgent service.

## Long input and secrets

- Use `--description-file`, `--description-stdin`, `note --file`, or
  `note --stdin` for long Markdown instead of shell-escaping large text.
- Notes are append-style and better for durable handoff context than scratch
  work.
- Avoid writing secrets into titles, descriptions, labels, projects, notes, or
  logs.
- Use the safe text workflow for descriptions:
  `aven text get <ref> description --output description.md`
  `aven text diff <ref> description --file description.md`
  `aven text set <ref> description --file description.md --if-sha256 <sha256>`

## Conflicts

```sh
aven conflict list
aven conflict show APP-7KQ9
aven conflict diff APP-7KQ9 description
```

- Inspect conflicts before resolving them.