Command reference

This page documents every user-facing aven command. The command line accepts global options before or after a subcommand.

Global syntax

aven [--db <path>] [--workspace <name-or-key>] <command>
aven help [<command>...]
aven --version

Option	Description
--db <path>	Use a specific SQLite database. This takes precedence over AVEN_DB, local.db_path, and the default state directory.
--workspace <name-or-key>	Use a specific workspace instead of directory routing or the configured default.
-h, --help	Print help for the selected command.
-V, --version	Print the installed aven version.

aven help <command> and aven <command> --help show the same command-specific help. Nested help accepts the full command path, such as aven help project path add.

Common values and behavior

Task references

Commands accept the qualified references printed by aven, such as APP-7KQ9, or an unambiguous bare suffix such as 7KQ9. Typed suffixes must contain at least three characters. Aven lengthens displayed suffixes when needed to keep them unambiguous. O is treated as 0, and I or L is treated as 1 when resolving a reference.

Statuses and priorities

Valid statuses are inbox, backlog, todo, active, done, and canceled.

Valid priorities are none, low, medium, high, and urgent.

Task metadata

Custom task metadata uses repeatable KEY=VALUE assignments. Keys are normalized workspace field names, and values are opaque UTF-8 strings. An empty value is present metadata, while --remove-metadata KEY removes the value. See Task metadata for field rules, filtering, recurrence behavior, and sync semantics.

Text input

Commands that accept long text provide mutually exclusive inline, file, and standard-input forms. Pass only one source for a field. For example:

aven add "Document recovery" --description "Short description"
aven add "Document recovery" --description-file ./description.md
aven add "Document recovery" --description-stdin <<'EOF'
Explain the recovery workflow.
Include a verification step.
EOF

Structured output

The --json option is available on context, show, list, search, recur list, recur show, recur history, attachment add, attachment list, attachment get, attachment delete, attachment prune, dep list, related list, epic list, prime, label list, metadata list, metadata show, project list, conflict list, conflict show, and doctor. JSON task objects from list, show, and search include scheduling in available_at and due_on, epic membership in is_epic, epic_parent, and epic_children, dependency counts in blocked_by and blocks, conflict state in has_conflict, and created_at and updated_at timestamps. Search results add score, matched_field, and snippet to this task shape. context --json and show --full --json expose custom task metadata as a key-value object and as detailed records with stable field IDs. They also expose related tasks and attachment metadata without bytes, including deleted attachment tombstones. Consumers must inspect each attachment’s deleted field. An empty available_at means immediate availability. An empty due_on means no deadline.

Temporal input

Availability input

Availability controls when a task becomes eligible for attention and enters normal task lists and queue groups. It is not a deadline or due date. An empty available_at value means the task is immediately available. aven add --available-at, aven edit --available-at, natural task intake, and the TUI task composer use the same expressions:

Expression	Local-calendar meaning
today	Today at local midnight.
tomorrow	Tomorrow at local midnight.
Nd, Nw	Local midnight after N calendar days or weeks, such as 2d or 3w.
in N days	Local midnight after N calendar days. Singular day is accepted.
in N weeks	Local midnight after N * 7 calendar days. Singular week is accepted.
in N months	The same local day after N calendar months. End-of-month dates clamp to the last valid day. Singular month is accepted.
next week	The next Monday strictly after today at local midnight.
next monday	The named weekday strictly after today at local midnight. Full names and common abbreviations such as mon, tues, and thurs are accepted. If today is that weekday, this means seven days later.
<date expression> at <time>	The expression’s local date at HH:MM, 9am, 9:30pm, noon, or midnight.
YYYY-MM-DD	Local midnight on that date.
YYYY-MM-DDTHH:MM:SSZ	The exact UTC timestamp. The same form without Z is also interpreted as UTC.
Unix timestamp	The exact whole number of seconds since the Unix epoch.
now	Immediate availability. On aven edit, --clear-available-at is clearer.

Relative expressions add calendar units to the current local date rather than fixed durations. Local expressions use the machine’s local timezone and convert to a canonical UTC timestamp for storage. This preserves the requested local wall-clock time across daylight-saving offsets. A local time that is skipped or repeated by a timezone transition is rejected, so use another local time or an explicit UTC timestamp.

Bare weekdays such as monday and bare times such as 9am are ambiguous and rejected with a suggested explicit form. Informal periods such as morning, recurrence, year arithmetic, and notifications are outside the accepted grammar.

aven add "Prepare demo" --available-at "in 2 weeks"
aven add "Call supplier" --available-at "next monday at 9am"
aven edit APP-7KQ9 --available-at "tomorrow at 14:30"

Due date input

A due date describes when completion is expected. It does not control visibility, change status, or clear availability. With reminders on, due and overdue tasks appear in the daily digest. A task can be available before its deadline, deferred beyond its deadline, or have either field on its own.

aven add --due, aven edit --due, natural task intake, and the TUI use the date expressions from Availability input, including compact offsets, calendar months, next week, named weekdays, and ISO dates. Due dates are local-calendar values stored as YYYY-MM-DD. They reject times, UTC timestamps, and Unix timestamps because a deadline is date-only.

Use none, clear, or aven edit --clear-due to remove a deadline. A due date equal to today is due today. It becomes overdue when the local date advances past it.

aven add "Submit report" --due "next fri"
aven edit APP-7KQ9 --due "in 1 month"
aven edit APP-7KQ9 --clear-due
aven list --overdue

Recurrence input

aven add --repeat accepts these exact forms:

Value	Schedule
daily	Every day.
every N days	Every N local calendar days from the start date.
weekdays	Monday through Friday.
weekly	Every week on the start date’s weekday.
fortnightly	Every two weeks on the start date’s weekday.
monthly	The start date’s day number every month.
every N months	Every N months on the anchored, clamped start day.
yearly	Every year on the anchored month and clamped day.
every N years	Every N years on the anchored month and clamped day.
weekly on mon,wed,fri	The selected weekdays every week.
every N weeks	Every N weeks on the start date’s weekday.
every N weeks on mon,thu	The selected weekdays every N weeks.

Explicit weekdays use the canonical abbreviations mon, tue, wed, thu, fri, sat, and sun, listed in Monday-to-Sunday order. N must be a positive whole number. Weeks begin on Monday, and weekday selections apply only to weekly schedules.

Schedules are anchored to their start date. Daily intervals count local calendar days. Monthly and yearly schedules use the final day when the anchored day is absent, then derive later dates from the original anchor without drift. A yearly schedule starting on February 29 uses February 28 in non-leap years and returns to February 29 in leap years.

The TUI schedule field also accepts friendly forms such as every day, every 3 days, every Friday, Fridays, every month, every 3 months, annually, every year, and every 3 weeks on Monday and Thursday. See Recurring tasks for creation workflows and schedule behavior.

Task commands

aven add

Create a task in the active workspace.

aven add <title> [options]

Argument or option	Description
<title>	Task title. With --natural, this is the natural-language task request.
--project <project>	Create the task in this project. Without it, aven infers a project from the current directory and creates that project when needed.
--description <text>	Set the description inline.
--description-file <path>	Read the description from a UTF-8 file.
--description-stdin	Read the description from standard input.
--priority <priority>	Set the priority. Defaults to none.
--status <status>	Set the initial status. Plain tasks default to inbox; recurring tasks default to todo and require an open status.
--available-at <when>	Defer the task until a calendar expression or timestamp. See Availability input.
--due <when>	Set a date-only deadline. See Due date input.
--repeat <rule>	Create a recurring task using a value from Recurrence input.
--repeat-at <HH:MM>	Make each dated task available at this local time in the recurring task’s time zone.
--repeat-due <same-day|none>	Make each dated task due on its scheduled date or leave it without a due date. Defaults to same-day.
--time-zone <IANA-zone>	Interpret scheduled dates and local times in this IANA time zone. Defaults to the device zone.
--repeat-start-on <YYYY-MM-DD>	Set the first eligible scheduled date. Defaults to the creation date in the recurring task’s time zone.
--label <label>	Add a label. Repeat for multiple labels. Labels must already exist.
--metadata <KEY=VALUE>	Assign custom task metadata. Repeat for multiple fields. A field is created in the workspace when its key is first used.
--epic	Create an epic container.
--natural	Parse the title as natural-language task intake using the configured agent command.

A plain task starts with status inbox. A recurring task starts with status todo and prints both its stable RCR- reference and first task reference. See Recurrence input for the accepted --repeat values. --available-at and --due cannot be combined with --repeat; use --repeat-at and --repeat-due instead.

--natural can be combined with --project, which fixes the project context and wins over any project returned by the configured intake command. It cannot be combined with a description source, --status, --priority, --label, --metadata, --epic, or scheduling flags. Natural intake can infer a title, description, project, priority, labels, availability, due date, and recurrence schedule. Ordinary natural intake uses status inbox and creates a non-epic task. Recurring natural intake uses status todo.

The command prints the created task’s qualified reference and bare suffix.

aven add "Fix conflict display" --project aven --status todo --priority high --label bug
aven add "Review migration plan" --metadata source=github --metadata review-state=pending
aven add "Review launch notes" --available-at "next monday at 9am"
aven add "Submit expense report" --due "next fri"
aven add "Add release automation" --epic
aven add "Daily journal" --repeat daily --repeat-at 09:00 --time-zone Europe/Stockholm
aven add "Review invoices" --repeat monthly --repeat-start-on 2026-01-31
aven add "Plan next sprint" --repeat fortnightly --repeat-start-on 2026-07-27
aven add --natural "high priority docs task for the aven project"
aven add --natural "draft release notes" --project aven

aven list

List tasks in the active workspace. Results are ordered by most recent update first. By default, deleted tasks are excluded.

aven list [options]

Option	Description
--project <project>	Match one project.
--status <status>	Match one status.
--priority <priority>	Match one priority.
--label <label>	Match one label.
--metadata <KEY=VALUE>	Match an exact custom metadata value. Repeat to require multiple values.
--has-metadata <KEY>	Match tasks with a value for this metadata field, including an empty string.
--missing-metadata <KEY>	Match tasks without a value for this metadata field.
--open	Show available, live tasks whose status is not done or canceled.
--all	Include deleted tasks alongside live tasks.
--deleted	Show deleted tasks only. Normal filters still apply.
--ready	Show open, non-epic tasks with no unresolved blocker.
--blocked	Show open tasks with at least one unresolved blocker.
--epics	Show epic containers only.
--upcoming	Show open, live tasks with a future availability time, ordered by availability time from earliest to latest.
--overdue	Show open, live tasks with a due date before today, ordered by due date from oldest to newest.
--expand-recurring	Show each dated recurring task as a separate row instead of grouping past tasks by recurring task.
--limit <number>	Return at most this many tasks after sorting and filtering. The value must be at least 1.
--json	Print a JSON array.

Normal lists hide open tasks whose availability time is in the future. They include tasks with empty or elapsed availability. --open also excludes done and canceled tasks and composes with project, priority, label, dependency, epic, overdue, recurrence-expansion, and limit filters. It cannot be combined with --status, --all, --deleted, or --upcoming. Explicit --status done and --status canceled lists include matching tasks regardless of availability, and --deleted includes matching deleted tasks regardless of availability.

--upcoming finds only live tasks with an open status and a future availability time. It can be combined with --project, --status, --priority, --label, --all, --overdue, and --limit. --all does not add deleted tasks to Upcoming. --upcoming cannot be combined with --ready, --blocked, --epics, or --deleted.

--overdue finds open, live tasks whose due_on date is earlier than the current local date. Due today is not overdue. Normal availability filtering still applies, so deferred overdue tasks remain hidden. Combine --upcoming --overdue to inspect deferred tasks whose deadlines passed.

--ready and --blocked are mutually exclusive. Neither can be combined with --all or --deleted. --ready and --epics are also mutually exclusive.

aven list --status active
aven list --open
aven list --open --project aven --label bug --limit 20
aven list --metadata review-state=pending
aven list --has-metadata effort
aven list --missing-metadata release-channel
aven list --ready
aven list --upcoming
aven list --upcoming --project aven --limit 10
aven list --overdue
aven list --upcoming --overdue
aven list --deleted --json

aven search

Search task references, titles, descriptions, projects, labels, notes, statuses, priorities, and current attachment filenames and alternative text across the active workspace. Pass --project to restrict every candidate source to one project before ranking and limiting. Done and canceled tasks participate in normal search. Deleted tasks require --all.

aven search <query>... [--project <project>] [--metadata <KEY=VALUE>] \
  [--has-metadata <KEY>] [--missing-metadata <KEY>] \
  [--limit <number>] [--all] [--expand-recurring] [--json]

Argument or option	Description
<query>...	One or more search terms. Multiple shell arguments are joined with spaces.
--project <project>	Search only the selected project, resolved by key or name in the active workspace.
--metadata <KEY=VALUE>	Restrict candidates to an exact custom metadata value. Repeat to require multiple values.
--has-metadata <KEY>	Restrict candidates to tasks with a value for this metadata field.
--missing-metadata <KEY>	Restrict candidates to tasks without a value for this metadata field.
--limit <number>	Maximum result count. Must be at least 1 and defaults to 50.
--all	Include deleted tasks.
--expand-recurring	Return each matching dated task instead of grouping past matches by recurring task.
--json	Print ranked results as JSON. Each result uses the list task shape and adds score, matched field, and optional snippet.

Text output identifies the matched field and score and prints a snippet when available. Search JSON preserves the flat task fields used by list JSON, including recurrence metadata and recurrence grouping, then adds score, matched_field, and snippet. Ref-shaped input can resolve a deleted task when --all is present.

aven search "auth bug"
aven search --project app "auth bug"
aven search "migration" --metadata source=github
aven search "handoff" --has-metadata review-state
aven search APP-7KQ9
aven search recovery --all --json

aven context

Print an agent-focused context snapshot for one task.

aven context <task-ref> [--full] [--json]

The snapshot includes stable identity, display reference, task fields, description, custom task metadata, project and workspace metadata, labels, notes, dependencies, dependents, related tasks, epic membership, recurring-task metadata, deletion state, and unresolved conflicts. It also derives whether the task is blocked, has conflicts, or blocks open work.

Text output omits empty fields and sections, and always prints the full description and metadata. Notes are chronological. On tasks with long note histories, earlier notes are left out so repeated checks stay small:

• The two newest notes always print. Earlier notes print while all printed note bodies fit 4,500 characters. If the remaining earlier notes total 1,500 characters or less, they print too.
• Each left-out note prints as one line: note id=<id> created=<time> chars=<n> excerpt=<opening text>.
• A note body over 8,000 characters is cut at a line boundary and followed by note truncated id=<id> shown_chars=<n> total_chars=<n>.
• When anything is left out or cut, a notes total=<n> shown=<n> omitted=<n> omitted_chars=<n> line comes before the notes, and the last line is read="aven note-show <task-ref> <note-id>...", which prints every missing body in one call.

Option	Description
--full	Print every note body in full.
--json	Print the complete snapshot as JSON. JSON output is never shortened.

aven context APP-7KQ9
aven context APP-7KQ9 --full
aven context APP-7KQ9 --json

aven show

Show one task.

aven show <task-ref> [--full] [--json]

Option	Description
--full	Include the description, custom metadata, project prefix, dependency summary, notes, and unresolved conflicts.
--json	Print JSON. With --full, emit the expanded task object.

The compact form prints the task’s main fields and relationships. Use context when workspace and project metadata or derived state flags are also needed.

aven show APP-7KQ9
aven show APP-7KQ9 --full
aven show APP-7KQ9 --full --json

aven recur

Inspect and manage recurring tasks. See Recurring tasks for creation workflows, schedule behavior, and lifecycle guidance. Every command that takes a reference accepts the recurring task’s RCR-7KP2 reference or any linked task reference.

recur list

aven recur list [--json]

Print one row per recurring task with its active, paused, or stopped state, schedule, time zone, next task reference, and history counts.

recur show

aven recur show <recurring-or-task-ref> [--json]

Show the schedule, settings used for future tasks, template metadata, next task, history summary, and unresolved state conflicts.

recur history

aven recur history <recurring-or-task-ref> \
  [--offset <number>] [--limit <number>] [--json]

History includes completed, skipped, and missed dates plus pause periods. A missed date may include a task reference when Aven created a task for that date. --offset defaults to 0, and --limit defaults to 100. An explicit --limit must be between 1 and 500, inclusive.

The JSON output from recur list, recur show, and recur history uses version: 1 and a command-specific kind value.

recur edit

aven recur edit <recurring-or-task-ref> [options]

Option	Description
--title <title>	Change the title used by future tasks.
--description <text>	Change the future description inline.
--description-file <path>	Read the future description from a UTF-8 file.
--description-stdin	Read the future description from standard input.
--project <project>	Change future tasks to an existing project.
--status <status>	Change the starting status used by future tasks.
--priority <priority>	Change the priority used by future tasks.
--label <label>	Replace future labels. Repeat for multiple labels.
--metadata <KEY=VALUE>	Assign metadata to the recurring template used by future tasks. Repeat for multiple fields.
--remove-metadata <KEY>	Remove metadata from the recurring template used by future tasks. Repeat for multiple fields.
--repeat-at <HH:MM|none>	Change or clear the future availability time.
--repeat-due <same-day|none>	Change the future due setting.

These options affect tasks created later. They do not rewrite the current task or history. The repetition pattern, start date, and time zone cannot be edited.

recur skip

aven recur skip <recurring-or-task-ref>

Mark the current task canceled, record its scheduled date as skipped, and create the next task. Setting the current task’s ordinary status to canceled has the same result.

recur pause and recur resume

aven recur pause <recurring-or-task-ref>
aven recur resume <recurring-or-task-ref>

Pause hides the current task from normal active views and suppresses scheduled dates until resume. Resume continues without creating tasks for the paused period.

recur stop

aven recur stop <recurring-or-task-ref> [--skip-current]

Stop ends future scheduling and leaves the current task available as the last one. --skip-current also marks that task canceled and records its date as skipped.

Done lists and search results group past tasks by recurring task. Pass --expand-recurring to aven list or aven search for one row per dated task. Task JSON includes nullable recurrence and recurrence_group objects.

aven attachment

Manage task image attachments without changing task descriptions.

aven attachment add <task-ref> <path> [--alt <text>] [--filename <name>] [--media-type <type>] [--optimize | --no-optimize] [--json]
aven attachment list <task-ref> [--all] [--json]
aven attachment get <attachment-id> [--output <path>] [--all] [--json]
aven attachment delete <attachment-id> [--json]
aven attachment prune [--dry-run | --apply] [--json]

Attachment metadata determines identity, display order, and search matches. Attachment IDs are exact, workspace-scoped 16-character uppercase Crockford Base32 identifiers. Task-ref suffix and normalization rules do not apply. Live attachments appear in (created_at, attachment_id) order. Attachment list and get require --all to include tombstoned metadata. Human-readable task attachment sections expose live attachments only. aven context --json and aven show --full --json preserve live attachments and deleted tombstones for synchronization-aware consumers. Inspect each attachment’s deleted field rather than treating every array entry as current. Compact aven show --json has no attachment array.

Add an image

Create the task first, then attach an image from a filesystem path:

aven attachment add APP-7KQ9 ./diagram.png --alt "service layout"
aven attachment add APP-7KQ9 ./capture --filename error.webp --media-type image/webp

The filename defaults to the file’s basename. Use --filename to choose another display name and --alt to add searchable alternative text. --media-type checks that the file has the expected format; it does not convert the image. The regular aven add command has no attachment option.

List and retrieve images

list shows a task’s current attachments in the order they were added. Pass --all to include deleted attachments. Human-readable output is compact; use --json for filenames, alternative text, dimensions, and local file availability.

aven attachment list APP-7KQ9
aven attachment list APP-7KQ9 --json

Copy the full attachment ID from this output when using get or delete. Attachment IDs are exact, workspace-scoped 16-character uppercase Crockford Base32 values and cannot be abbreviated like task refs.

get prints attachment information by default. Add --output to save the image to a file. Aven refuses to overwrite an existing path.

aven attachment get 7KQ9A1X4MV2P8D6R
aven attachment get 7KQ9A1X4MV2P8D6R --output ./diagram.png

Saving the file requires the image to be available on this device. In JSON output, has_blob: true means it is available. If it is not, run sync or restore a backup that includes images.

Delete an attachment

delete removes the attachment from its task. Repeating the command is safe. Aven has no attachment restore command.

aven attachment delete 7KQ9A1X4MV2P8D6R

A tombstone records deletion independently of local blob retention. attachment get <id> --all inspects tombstoned metadata, but tombstone metadata does not guarantee that image bytes remain retrievable. --output succeeds only while the blob is available on this device. Normal sync does not download deleted attachment blobs, and pruning may remove an unused blob after the grace period. Use a backup when deleted image bytes must be retained.

Supported images and optimization

Aven checks the actual image rather than trusting its extension. It accepts nonempty PNG, JPEG, GIF, and WebP files with these limits:

Item	Limit
Image file	25 MiB
Width or height	16,384 pixels
Pixels in one frame	40,000,000
Animation frames	100
Pixels across an animation	100,000,000
Filename	1-255 UTF-8 bytes, with no control characters or path separators
Alternative text	500 UTF-8 bytes, with no control characters

Aven checks the complete image, including every animation frame, before attaching it. --optimize requests lossless PNG optimization, while --no-optimize preserves the file. Without either flag, local.image_optimization controls CLI attachments and defaults to off. Optimization applies only to PNG files. Aven preserves the original when optimization fails or does not reduce the file size, and validates any optimized file before storage.

JSON output and search

JSON output from add, list, get, and delete contains attachment_id, task_id, sha256, byte_size, media_type, filename, alt_text, width, height, created_at, deleted, deleted_at, and has_blob. Add output also contains optimized.

context --json and show --full --json include live attachment metadata and deleted tombstones except sha256. Consumers must inspect deleted; deleted_at records when a tombstone was created. Human-readable task attachment sections and search use live attachments only. attachment list --all and attachment get --all expose tombstoned metadata directly. Compact show --json has no attachment array. Search matches live attachment filenames and alternative text, not image contents or hashes.

Clean up unused images

attachment prune reports image files eligible for cleanup. It performs a dry run by default. Pass --apply to delete them. JSON output contains mode, eligible_count, eligible_bytes, pruned_count, and pruned_bytes.

Cleanup honors the configured grace period and processes at most local.attachment_lifecycle.maintenance_limit files per run, so large cleanups may require repeated runs. Images used by tasks or attachment operations in progress are protected. Identical images share storage and count once toward attachment quotas. Cached previews are disposable and may be cleaned during either a dry run or an applied cleanup.

aven edit

Update fields on one task.

aven edit <task-ref> [options]

Option	Description
--title <title>	Replace the title.
--description <text>	Replace the description inline.
--description-file <path>	Replace the description from a UTF-8 file.
--description-stdin	Replace the description from standard input.
--project <project>	Move the task to an existing project.
--status <status>	Set the status.
--priority <priority>	Set the priority.
--available-at <when>	Set or reschedule availability with a calendar expression or timestamp. Passing now makes the task immediately available. See Availability input.
--clear-available-at	Clear availability so the task is immediately available.
--due <when>	Set or reschedule the date-only deadline. Passing none or clear removes it. See Due date input.
--clear-due	Remove the due date.
--epic <on-or-off>	Set epic state. Accepted true values are on, true, and 1; accepted false values are off, false, and 0.
--label <label>	Add an existing label. Repeat as needed.
--remove-label <label>	Remove a label. Repeat as needed.
--metadata <KEY=VALUE>	Assign custom metadata. Repeat for multiple fields. An empty value remains present metadata.
--remove-metadata <KEY>	Remove custom metadata. Repeat for multiple fields.

Description sources are mutually exclusive. --available-at and --clear-available-at are mutually exclusive. --due and --clear-due are mutually exclusive. The same metadata key cannot appear in both --metadata and --remove-metadata. Aven reports whether the update changed the task.

A task with epic children cannot have epic state turned off. Epic containers cannot become children of another epic.

aven edit APP-7KQ9 --status active
aven edit APP-7KQ9 --title "Clarify conflict output" --priority medium
aven edit APP-7KQ9 --available-at "in 2 weeks at 14:30"
aven edit APP-7KQ9 --clear-available-at
aven edit APP-7KQ9 --due "in 1 month"
aven edit APP-7KQ9 --clear-due
aven edit APP-7KQ9 --label docs --remove-label bug
aven edit APP-7KQ9 --metadata effort=large --metadata review-state=pending
aven edit APP-7KQ9 --remove-metadata review-state
aven edit APP-7KQ0 --epic on

aven move

Move tasks to an existing project in another workspace.

aven move <task-ref>... --to-workspace <workspace> --project <project>

The active workspace is the source. Task IDs and ref suffixes stay the same; the project prefix changes. Notes, labels, custom metadata, attachments and internal relationships move with the tasks. Labels and metadata fields match by name or key in the destination. Moving an epic includes its complete subtree, including deleted children.

A move is atomic and cannot be undone through TUI undo. It refuses recurring tasks, unresolved conflicts and live dependencies, related links or epic links crossing the move boundary. A group may contain at most 256 tasks; its snapshot must fit the 64 KiB operation payload limit. If validation fails, nothing moves.

aven --workspace personal move APP-7KQ9 APP-7KQ0 \
  --to-workspace work --project app

The summary reports the moved count and source and destination workspace keys. Devices sharing the vault must support workspace moves.

aven note

Append a durable note to a task.

aven note <task-ref> [text] [--file <path> | --stdin]

Supply exactly one of [text], --file, or --stdin. The command prints the generated note ID, which note-delete accepts.

aven note APP-7KQ9 "Waiting for API review"
aven note APP-7KQ9 --file ./handoff.md
printf '%s\n' "Reproduces on clean install" | aven note APP-7KQ9 --stdin

aven note-delete

Delete a note from a task. Repeating the command for an already-deleted note succeeds and reports that no change was made.

aven note-delete <task-ref> <note-id>

aven note-delete APP-7KQ9 01JABCDEF123

aven note-show

Print complete note bodies by ID, in the task’s note order. aven context prints this command when it leaves notes out. If any ID is not a live note on the task, the command prints nothing and fails with error unknown-note.

aven note-show <task-ref> <note-id>... [--json]

aven note-show APP-7KQ9 01JABCDEF123 01JABCDEF456

aven dep

Inspect and modify task dependencies. In dep add <task> <blocker>, the first task depends on the second task.

aven dep add <task-ref> <depends-on-ref>
aven dep remove <task-ref> <depends-on-ref>
aven dep list <task-ref> [--json]

Dependencies must stay within one workspace. A task cannot depend on itself, and aven rejects dependency cycles. Adding or removing the same relationship repeatedly is safe and reports whether anything changed. A dependency is unresolved while its blocker is open.

aven dep add APP-7KQ9 APP-7KQ0
aven dep list APP-7KQ9
aven dep remove APP-7KQ9 APP-7KQ0

aven related

Explicitly link tasks that provide useful context without ordering or containment.

aven related add <task-ref> <related-ref>
aven related remove <task-ref> <related-ref>
aven related list <task-ref> [--json]

Links are symmetric and stay within one workspace, but may cross projects. They do not affect blocking, readiness, scheduling, queue order, or containment. References in titles, descriptions, or notes do not create links automatically. Use related add to create a link, related remove to unlink it from either endpoint, and related list to inspect one task’s links.

aven related add APP-7KQ9 WEB-7KQ0
aven related list APP-7KQ9 --json
aven related remove APP-7KQ9 WEB-7KQ0

aven epic

Inspect and modify epic membership.

aven epic add <child-ref> <epic-ref>
aven epic remove <child-ref> <epic-ref>
aven epic list <epic-ref> [--json]

epic add marks the parent as an epic when needed. Child and epic must belong to the same workspace and project. An epic cannot be its own child, epic containers cannot be children, and each child can belong to only one epic. Epic membership does not create a dependency or make a child blocked.

epic list prints the epic and all children, including child status, priority, and title.

aven epic add APP-7KQ9 APP-7KQ0
aven epic list APP-7KQ0 --json
aven epic remove APP-7KQ9 APP-7KQ0

aven text

Read and update long text with optimistic concurrency protection. The only supported text field is description.

aven text get <task-ref> description [--raw | --output <path>]
aven text diff <task-ref> description --file <path>
aven text set <task-ref> description (--file <path> | --stdin) --if-sha256 <hash>

text get

Prints the current SHA-256 hash and description. --raw writes only the description with no added newline. --output writes the description to a file and prints its hash. Do not combine --raw and --output if downstream output must remain machine-oriented, because --output takes precedence.

text diff

Reads the candidate UTF-8 file and prints a unified-style comparison against the stored description. It does not modify the task.

text set

Reads the replacement from exactly one of --file or --stdin. The write succeeds only when --if-sha256 matches the hash of the stored description, preventing an unseen concurrent edit from being overwritten.

aven text get APP-7KQ9 description --output description.md
aven text diff APP-7KQ9 description --file description.md
aven text set APP-7KQ9 description --file description.md --if-sha256 <hash-from-get>

aven bulk-update

Apply the same field changes to a selected set of tasks.

aven bulk-update <selector>... <mutation>... [--dry-run] [--include-deleted]

Selectors:

Option	Description
--project <project>	Select tasks in one project.
--status <status>	Select tasks with one status.
--priority <priority>	Select tasks with one priority.
--filter-label <label>	Select tasks with one label.
--all	Explicitly select all live tasks when no narrower filter is appropriate.
--include-deleted	Include deleted tasks in the selected set. This is not itself a selector.

Mutations:

Option	Description
--set-status <status>	Set status.
--set-priority <priority>	Set priority.
--set-project <project>	Move tasks to an existing project.
--label <label>	Add an existing label. Repeat as needed.
--remove-label <label>	Remove a label. Repeat as needed.
--metadata <KEY=VALUE>	Assign custom metadata. Repeat for multiple fields.
--remove-metadata <KEY>	Remove custom metadata. Repeat for multiple fields.
--dry-run	Print the planned result without writing.

At least one selector and one mutation are required. Selector options combine as an intersection. Availability dates do not limit bulk selection, so future tasks are included when they match. The same label cannot appear in both --label and --remove-label, and the same metadata key cannot appear in both --metadata and --remove-metadata. Before any write, aven validates the entire selected set and rejects updates to fields with unresolved conflicts. A dry run does not create metadata fields. A bulk update commits all selected changes in one transaction, and any task failure rolls back the complete set. Successful output includes one line per task and a matched, changed, unchanged, and dry-run summary.

aven bulk-update --project aven --status todo --set-priority high --dry-run
aven bulk-update --project aven --metadata review-state=pending --dry-run
aven bulk-update --filter-label old --label migrated --remove-label old
aven bulk-update --all --remove-metadata review-note
aven bulk-update --all --set-status backlog

aven delete

Soft-delete one task.

aven delete <task-ref>

Deleted tasks stay in the database and can be found with list --deleted, list --all, or search --all.

aven delete APP-7KQ9

aven restore

Restore one soft-deleted task.

aven restore <task-ref>

aven restore APP-7KQ9

Workspace commands

aven workspace

Manage task universes in the database.

aven workspace list
aven workspace create <name>
aven workspace rename <workspace> <new-name>

list prints every workspace key and name. create derives a normalized key from the name. rename accepts a workspace name or key and updates its name and key.

aven workspace create "Client work"
aven workspace rename client-work "Consulting"
aven workspace list

aven project

Manage projects in the active workspace.

aven project create <name> [--path <path>]
aven project delete <project>
aven project list [--search <text>] [--limit <number>] [--json]
aven project rename <project> <new-name> [--prefix <prefix>]
aven project path add <project> <path>
aven project path remove <project> <path>
aven project path list [project]

project create

Creates a project with a normalized key and a unique display prefix. --path also records a canonical directory mapping in the config file.

project delete

Deletes a project from normal use and removes its path mappings. Active and paused recurring series assigned to the project are stopped, retaining their final projected tasks. Projects referenced by tasks or recurring series remain stored so those records retain project identity.

project list

Lists project keys, prefixes, and names. --search performs project search, --limit returns at most the requested positive number of results, and --json returns objects with key, name, and prefix.

project rename

Updates the project’s name, normalized key, and display prefix while preserving stable project identity. Without --prefix, aven generates a unique prefix from the new key. Existing managed config mappings are rewritten to the new project key.

project path

add and remove update managed path mappings in the config file. Paths are canonicalized. list prints all mappings or only mappings for the optional project.

aven project create "Aven docs" --path ~/code/aven/docs
aven project rename aven-docs "Documentation" --prefix DOC
aven project path add documentation ~/writing/aven
aven project path list documentation
aven project list --search doc --json

aven label

Manage labels in the active workspace.

aven label create <name>
aven label delete <name>
aven label list [--search <text>] [--limit <number>] [--json]

Label names are normalized. Labels must exist before add, edit, or bulk-update assigns them. Deleting a label removes its task assignments. Repeating deletion is safe and reports whether anything changed. label list --limit accepts positive values.

aven label create bug
aven label list --search bu
aven label delete bug

aven metadata

Inspect and rename custom metadata fields in the active workspace. Fields are created automatically when a task or recurring task template first uses a key.

aven metadata list [--json]
aven metadata show <key> [--json]
aven metadata rename <key> <new-key>

metadata list prints every field’s key, stable ID, task count, and recurring-template count. metadata show prints the same information for one key. metadata rename changes the displayed key while preserving the field ID and every related value. The previous key becomes available for a separate field. Metadata fields have no delete command.

aven metadata list --json
aven metadata show review-state
aven metadata rename review-state approval-state

See Task metadata for key rules, value semantics, filtering, and recurring task behavior.

Sync commands

aven sync

Exchange changes with the end-to-end encrypted sync server chosen during setup or join.

aven sync [--json]

Sync runs bounded rounds until tasks are up to date and image transfers settle, or until a round limit stops it. Output reports sent and received changes, open and newly created conflicts, and image state; --json emits the versioned counts and result. A database that has not been set up or joined fails with sync-not-set-up and stays usable locally.

aven sync setup

Start sync from this database with the invitation printed by aven server setup.

aven sync setup [--yes]

On macOS, interactive setup automatically uses a valid aven-setup: invitation from the clipboard. Otherwise, paste the invitation or pipe it to standard input. Setup previews the database, checks its image files, and lists missing images that will be published as unavailable. It asks for confirmation; --yes is required when standard input is not a terminal. Every other device starts from this data. Afterwards the database can still create backups, but restore and import are refused there. Rerun the command with an invitation from the same server to resume an interrupted setup whose server outcome was unknown. Setup remembers the server address before sending credentials and refuses to resume at a different address or without that saved address. To abandon setup and use another server, run aven sync reset --force. A definite rejection before setup is frozen leaves the database local-only.

aven sync invite

Invite another device and wait until it joins.

aven sync invite
aven sync invite --cancel

Standard output receives only the AVEN: invitation. Interactive standard error also shows it as a QR code, and the eventual Device added message is written to standard error. Anyone with the invitation can access all synced data and manage devices. It expires after ten minutes. Rerunning the command resumes the open invitation and reports its declared expiry.

Ctrl-C or --cancel retires an invitation before keys have been sent. If keys may already have been sent, it remains open until its expiry and the next sync changes keys. A second Ctrl-C force-quits while cancellation is in progress. Sync on this device keeps running while the invitation is open.

aven sync join

Join sync from an empty database with a device invitation.

aven sync join [--yes]
aven sync join --new-invitation [--yes]

Paste the invitation without terminal echo, or pipe it to standard input, while the inviting device waits. A fresh join shows the server and asks for confirmation; --yes is required for piped input. Joining downloads the synced data and then its images. Rerun aven sync join to resume an interrupted join without supplying the invitation. Use --new-invitation only when continuing with a replacement invitation from the original inviting device.

aven sync device

List devices in sync, or remove another device.

aven sync device list [--json]
aven sync device remove <device-id-or-prefix> [--json]

Both commands contact the server. Text list output is a table containing the automatic label when available, a unique short ID, and this device for the current device. It mentions an unfinished key update only while one is pending. The label is the macOS Computer Name or Linux hostname and is stored only in the encrypted synced data. JSON retains each full device_id, current, and admission_sequence value and adds label; it also retains key_rotation_pending.

remove accepts a full ID or a unique prefix of at least four hexadecimal characters. An ambiguous prefix lists its matches. Removal rotates keys for future changes, then reports state as complete or pending with access_revoked and key_rotation_pending. An interrupted removal fails with sync-device-removal-incomplete; use the full selected device_id to resume. Refusals include sync-device-id-invalid, sync-device-id-ambiguous, sync-device-not-found, and sync-device-current; a device cannot remove itself. Removal does not erase data the removed device already downloaded. JSON output is versioned and omits keys, credentials, and invitations.

A sync allows 256 device changes over its lifetime, at most 63 of them key rotations. Adding a device is one change. Removing a device, or changing keys after an invitation expired when it may have sent keys, is two: the change and its key rotation. Inviting a device requires room for one key rotation. Once a limit is reached, devices can no longer be added or removed; start a new sync from a backup as in Recover from device loss.

aven sync reset

Stop syncing this database and keep its data as a local database.

aven sync reset [--force] [--yes] [--json]

Deletes this database’s sync state, its unsent sync queue, and its protected sync keys. Tasks, images, and history stay and remain editable. Reset does not contact the server or change which devices take part in sync; remove this device from another device with aven sync device remove. Changes made here that never synced do not reach the previous sync.

Afterwards the database behaves as if it never synced: aven sync setup can start a new sync from it, and aven sync join still needs an empty database. Reset asks for confirmation; --yes is required when standard input is not a terminal. It is refused with sync-reset-join-in-progress or sync-reset-invitation-open while joining or an unexpired invitation is unfinished.

An unfinished setup is also refused by default because its server may have accepted the claim even when the client did not receive the response. If the original setup invitation or server storage is gone and setup cannot resume, --force abandons it after an additional warning. This can orphan a server that accepted the setup, but keeps local tasks, images, and history. JSON output reports state as reset, or not-set-up when the database did not take part in sync. The TUI has no reset action. See Rebuilding sync.

aven sync status

Inspect local sync state without contacting the server or starting a sync.

aven sync status
aven sync status --json

The state is not-set-up, setup-incomplete, join-incomplete, key-change-pending, access-refused, vault-deleted, or ready. key-change-pending means an invitation expired after keys may have been sent to a device that never joined; the next aven sync changes keys before uploading new changes. access-refused records when the server refused this device’s credentials. It may have been removed, but the refusal alone does not prove that; check from another device. Local tasks and images remain available, and a successful sync clears the state. vault-deleted records when the server reported this sync’s vault deleted, for example after a reset in the hosting portal. Automatic sync stops; local tasks and unsynced changes stay. Run aven sync reset, then aven sync setup with a new setup code. A successful aven sync also clears the state. Set-up databases also report the server, whether local changes wait to sync, open conflicts, pending image uploads, downloads, and unavailable images, plus whether an invitation is open and its expiry. Text output omits the internal server position; JSON retains it. The versioned JSON report omits invitation text, keys, and task content.

Command failures print a plain explanation, a next step, and a stable code in square brackets. The full internal error chain is written to the log rather than repeated on standard error.

aven server

Serve end-to-end encrypted sync from storage prepared by aven server setup.

aven server [--data <path>] [--bind <address>] [--unsafe-public-bind]
aven server setup [--data <path>] --url <url> [--invitation-only]

Option	Description
--data <path>	Server SQLite database path. Defaults to $STATE_DIRECTORY/sync-server.sqlite when systemd sets StateDirectory=, otherwise $XDG_STATE_HOME/aven/server/sync-server.sqlite (~/.local/state/aven/server/sync-server.sqlite). Pass the same path to both commands.
--bind <ip:port>	Listen address. Defaults to 127.0.0.1:3746. Loopback, private, and VPN addresses are accepted directly.
--unsafe-public-bind	Allow binding a public or wildcard address. Prints a warning because payload encryption does not protect credentials or setup invitations.
--url <url>	For setup: the HTTP or HTTPS origin devices use to reach the server, with no path, query, or credentials, and at most 255 bytes.
--invitation-only	For setup: print only the invitation, without operator instructions.

server setup stores an expiring setup verifier, then prints a setup invitation for aven sync setup, the storage path, and guidance to start the server on that storage so devices can reach the setup URL. With explicit --data, it reminds you to pass the same path to aven server. Use --invitation-only when a script needs the invitation without the operator instructions. Running setup again before a device claims the server replaces the invitation. The server does not terminate TLS. Device credentials, setup invitations, server identifiers, and traffic metadata are outside the end-to-end encrypted payload, so use HTTP only over a trusted VPN or another protected private network; otherwise put a TLS reverse proxy in front of it. Both commands refuse storage that holds change history, including storage from the unencrypted sync of earlier releases. The server shuts down gracefully on an operating-system termination signal.

aven server setup --data /srv/aven/server.sqlite --url http://100.100.20.30:3746
aven server --data /srv/aven/server.sqlite --bind 100.100.20.30:3746

aven conflict

Inspect and resolve unresolved sync conflicts.

aven conflict list [--project <project>] [--field <field>] [--limit <number>] [--json]
aven conflict show <task-ref> [--field <field>] [--json]
aven conflict diff <task-ref> <field>
aven conflict export <task-ref> <field> --dir <path>
aven conflict resolve <task-ref> <field> (--use <variant> | --value <text> | --value-file <path> | --value-stdin)

conflict list

Lists unresolved conflicts, optionally filtered by project and field. --limit returns at most the requested positive number of results. Output includes variant tokens needed by conflict resolve --use.

conflict show

Shows every unresolved conflict for a task or only the selected field. Values for project and label fields are rendered as user-facing keys and names rather than internal IDs.

conflict diff

Prints the local and remote values for a single conflict as a text diff. It requires exactly one unresolved conflict for the task and field.

conflict export

Creates the destination directory and writes each variant to <field>-<variant>.md for external inspection or merging.

conflict resolve

Resolve with a variant token from list or show, or provide a replacement value through exactly one inline, file, or standard-input source. --use takes precedence when supplied, so do not combine it with a value source.

aven conflict list --project aven
aven conflict show APP-7KQ9 --field description
aven conflict diff APP-7KQ9 description
aven conflict export APP-7KQ9 description --dir ./conflict-review
aven conflict resolve APP-7KQ9 description --use a
aven conflict resolve APP-7KQ9 description --value-file ./merged.md

aven daemon

Run synchronization and reminders continuously, or manage them as a background service on macOS or on Linux with systemd.

aven daemon
aven daemon status [--json]
aven daemon install [--program <path>]
aven daemon uninstall
aven daemon restart
aven daemon repair [--if-installed] [--program <path>]

Running aven daemon in the foreground requires sync.enabled: true, reminders.enabled: true, or both. With only reminders on, it sends reminders and does not sync. Until the database is set up or joined it waits without contacting a server. Once set up, it syncs immediately, then on the configured interval and whenever a local mutation sends a UDP wake signal. Failed syncs use exponential backoff up to five minutes. Bounded rounds with more work remaining resume promptly. The process exits when its executable changes so a service manager can restart the updated binary.

daemon status is observational. It reports platform support, installation, loaded and running state, executable consistency, configuration validity, service and log paths, and a recovery action. Its JSON states are unavailable, unconfigured, healthy, degraded, blocked, and failed.

Service management is available on macOS, as a LaunchAgent, and on Linux, as a systemd user service named aven-daemon.service:

• install writes, enables, and starts the service. It records the resolved database, config directory, and executable. On macOS it also records log paths, and an executable inside Aven.app is recorded by its bundle path so Login Items lists the daemon as Aven; on Linux output goes to the journal (journalctl --user -u aven-daemon.service). --program stores an explicit executable path instead of the running binary.
• uninstall stops and removes the service file.
• restart restarts the service.
• repair rewrites and restarts an installed service from active configuration. --if-installed succeeds without changes when the service is absent. --program selects the stored executable path.

On macOS, a daemon that runs Aven.app’s executable through a symlink, such as Homebrew’s bin/aven, moves its LaunchAgent to the bundle path when it starts. It keeps the recorded database, environment, and log paths, and reloads the service from a separate process. It leaves a disabled service, or a plist edited outside aven, unchanged; aven daemon status then suggests aven daemon repair.

On Linux, a systemd user service stops when you log out unless lingering is enabled with loginctl enable-linger.

aven daemon
aven daemon status
aven daemon status --json
aven daemon install
aven daemon repair --if-installed
aven daemon restart

Interactive commands

aven demo

Open the TUI with a fresh temporary database containing the curated sample projects, labels, tasks, dependencies, related links, and epic membership used in product screenshots.

aven demo

aven tui

Open the terminal user interface.

aven tui [<task-ref>] [--view <view>] [--layout <layout>] [-p [<project>] | --project [<project>]] [--label <label>] [--priority <priority>] [--add-task | --add-task-only] [--natural]

Argument or option	Description
[<task-ref>]	Open a task detail directly. Task refs cannot be combined with browse context or composer options.
--view <view>	Start with the queue, ready, blocked, overdue, all, open, inbox, active, backlog, todo, done, upcoming, conflicts, epics, recurring, or recent-actions query.
--layout <layout>	Present a compatible query as list or columns.
-p, --project [<project>]	Start in a project. Passing the flag without a value uses the project inferred from the current directory. Omitting the flag starts with workspace scope.
--label <label>	Apply an initial label filter.
--priority <priority>	Apply an initial none, low, medium, high, or urgent priority filter.
--add-task	Open the add-task composer over the selected browse context.
--add-task-only	Run only the add-task popup and exit after submission or cancellation. Project scope remains available.
--natural	Use natural-language intake. Requires --add-task or --add-task-only.

Queries, layout, project scope, label, priority, and --add-task compose. Columns supports all, open, ready, blocked, overdue, status, and conflicts queries. Incompatible query and layout pairs fail at launch. The recent-actions query rejects label and priority filters because it displays change-log entries rather than tasks. --add-task and --add-task-only are mutually exclusive.

aven tui
aven tui --project aven --view todo --label bug
aven tui --view all --layout columns
aven tui AVN-7KQ9
aven tui --add-task --natural
aven tui --project aven --add-task-only

Agent commands

aven prime

Emit an agent primer plus open work for an inferred or selected project.

aven prime [--project <project>] [--limit <number>] [--json]

Without --project, aven infers the project from the current directory. Text output includes CLI conventions, an issue workflow, actionable task-title guidance, sampled status and label frequencies, top blockers, and open tasks partitioned into Active, Ready, and Blocked. Epic containers and done or canceled tasks are excluded.

--json emits project context, conventions, top blockers, and the same task partitions. --limit bounds the task sample in both text and JSON output and accepts positive values.

aven prime
aven prime --project aven
aven prime --project aven --limit 20 --json

aven skill

Print or install aven’s coding-agent skill.

aven skill
aven skill install [--agent <agent>]...

With no subcommand, aven skill prints the embedded skill Markdown to standard output. skill install writes the skill into detected coding-agent skill directories. --agent is repeatable and accepts claude, opencode, codex, or pi. Without explicit targets, aven installs to all detected supported agents.

aven skill > /tmp/aven-skill.md
aven skill install
aven skill install --agent claude --agent codex
aven skill install --agent pi

Pi receives the bundled skill at ~/.pi/agent/skills/aven/SKILL.md. The other user locations are ~/.claude/skills/aven/SKILL.md for Claude Code, ~/.config/opencode/skills/aven/SKILL.md for OpenCode, and ~/.codex/skills/aven/SKILL.md for Codex.

Setup commands

aven config

Create, inspect, or update the config file.

aven config init
aven config show
aven config get <key>
aven config set <key> <value>

config init creates the default config.yaml and fails rather than overwriting an existing file. config show prints the resolved config path followed by its stored text. config get prints one non-secret scalar value, and config set validates and atomically updates one scalar while preserving comments and unrelated settings. Optional string settings print null when unset and accept null to clear them. See Configuration for the supported keys and value formats. The config directory comes from AVEN_CONFIG_DIR or the platform default.

aven doctor

Diagnose startup, configuration, routing, storage, sync, and daemon state without changing user data.

aven doctor [--integrity] [--json] [--fail-on-error]

Doctor has a standalone bootstrap path. It can report malformed or invalid configuration, an unreadable or missing database path, invalid SQLite files, pending or failed migrations, and unsupported future schemas even when ordinary commands cannot start. Database path precedence remains --db, AVEN_DEV_DB in debug builds, AVEN_DB, local.db_path, and the platform default. When strict config loading fails, doctor can still use a syntactically readable local.db_path while marking config-dependent checks as skipped.

Database inspection uses an isolated snapshot and never creates or changes the selected database, initializes metadata or a workspace, enables WAL, runs migrations, or removes sidecars. Checks that reconcile derived state operate only on the disposable snapshot. Doctor performs no sync, daemon wakeup, update check, network request, or repair. A missing database remains missing. Pending migrations are reported with backup and normal-startup guidance.

The report includes config and database paths and their sources, schema and sidecar state, workspace counts, client and sequence metadata, sync configuration and recent sync state, unresolved conflict count, daemon wake settings, and service status on macOS and Linux. Attachment checks report image storage, cleanup eligibility, quotas, operations in progress, and inconsistencies. Independent sections continue after failures, while dependent checks use skipped status and include a reason.

Normal doctor checks attachment records and local image availability. --integrity also runs read-only SQLite and relationship checks, verifies recurring schedules, generated tasks, history, pauses, and lifecycle state, verifies stored image hashes and sizes, decodes images, and confirms formats and dimensions. A missing current recurring task is a repairable warning with guidance to run aven recur list. Other recurring-task integrity failures include guidance to preserve the database and recover from a known-good backup.

--json emits a typed report with overall_status, section and check status, stable check codes, values, and explicit skipped_reason fields. Doctor keeps its compatible zero exit status by default so findings remain report data. Add --fail-on-error when automation needs a nonzero exit status for error-level findings. Warnings alone do not make this mode fail.

Configuration diagnostics include the config path and available YAML line and column context. They never print auth tokens or raw secret values. Doctor output also excludes task content and raw sync payloads.

aven doctor
aven doctor --integrity
aven doctor --json --fail-on-error

aven completions

Print a static completion script for subcommands, flags, and enumerated values.

aven completions <bash|zsh|fish|elvish|powershell>

Write the output to your shell’s completion directory, for example: aven completions fish > ~/.config/fish/completions/aven.fish. Homebrew installs completions automatically.

aven update

Check GitHub releases for a newer aven version.

aven update [--yes]

Package-manager installations receive manager-specific update instructions. Direct installations report an available release without changing the executable unless --yes is supplied.

A direct update downloads the platform archive, verifies it, replaces the current executable, and asks you to restart running aven processes. Cached release information is used when a fresh check fails and a valid cache entry exists.

On macOS, aven runs from Aven.app, and a direct update replaces the whole bundle. A standalone aven executable is replaced by a symlink to ~/.local/share/aven/Aven.app/Contents/MacOS/aven. An installed daemon restarts on the new executable and moves its LaunchAgent into the bundle.

aven update
aven update --yes

Data safety commands

aven backup

Create or restore a compressed backup archive.

aven backup [--output <path>]
aven backup restore <path> --yes

Without --output, backup creates a timestamped .aven-backup.tar.zst archive beside the active database. The archive contains a consistent database backup and every attachment image available on this device. The database preserves recurring schedules, future-task settings, completed, skipped, and missed history, pauses, conflicts, and task-specific notes and attachments. Attachment records for missing images remain in the database, but the missing files cannot be included. Cached previews and incomplete files are excluded. Aven validates every included image while creating the archive.

Backups work for databases that take part in sync, including incomplete setup or joining. Sync bindings, enrollment state, and encryption keys are excluded, so restoring to a fresh path creates a local-only database.

backup restore requires --yes. Restore checks the archive, database, attachment information, and image files before replacing local data. It creates safety copies of the existing database and attachment directory first. Plain SQLite backup files remain accepted for database-only recovery. Restore is refused when the target database takes part in sync; use a fresh database path instead.

aven backup
aven backup --output ~/backups/aven.aven-backup.tar.zst
aven backup restore ~/backups/aven.aven-backup.tar.zst --yes

aven export

Export portable user and sync metadata as JSON.

aven export --output <path>

The export includes tasks, recurring schedules, future-task settings, history, pauses, conflicts, and attachment information. Past dated tasks remain ordinary task rows. Image files are excluded and blobs_included is false. Parent directories are created as needed. The command reports workspace and task counts and output size. An export from a database that has set up or joined sync can’t be imported; use aven backup for synced data.

aven export --output ~/backups/aven.json

aven import

Replace local data from an aven JSON export.

aven import <path> --yes

Import requires explicit confirmation with --yes. Aven validates the export, relationships, attachment information, recurring schedules, generated tasks, history, pauses, and active, paused, or stopped state before replacing local data. It creates a safety backup, preserves this installation’s client identity, clears server-specific sync state, and runs integrity checks. Past dated tasks keep their own fields, notes, and attachment metadata. Because JSON contains no image files, imported attachments are marked unavailable and are not published by sync; use a backup archive when moving images.

Exports without recurrence sections import every task as nonrecurring data.

aven import ~/backups/aven.json --yes