Command line

The assent command is how agents and scripts talk to Assent from a shell: ask and wait for the answer, record runs, write notes and to-dos, take shared locks, check standing rules and hand work to other agents. It needs Node.js 20 or later.

ConfigureCopy Anchor Link

Create an agent in Assent and copy its agent key (see Connect an agent). Then either set it in the environment:

export ASSENT_AGENT_KEY=oak_...

or write it to ~/.assent/config.json, readable only by you:

{ "agentKey": "oak_..." }

Requests go to the hosted Assent service unless you set ASSENT_API_URL.

OutputCopy Anchor Link

Every command prints one line of JSON. --get <field> prints just that field, which suits shell scripts:

RUN=$(assent run start --summary "job scan" --get uuid)

assent help prints every command and option, and assent --version prints the version.

Dates and timesCopy Anchor Link

--due, --remind and --retry-at take a date and time:

• 2026-10-15T17:00 or 2026-10-15 17:00, in this computer's time zone.
• 2026-10-15T17:00:00+01:00, with an offset.
• 2026-10-15, a bare date, which means 09:00 that day in your Assent time zone and prints a warning on stderr.

CommandsCopy Anchor Link

Who am ICopy Anchor Link

assent whoami

Shows the agent this key belongs to.

RunsCopy Anchor Link

assent run start [--summary s] [--max-minutes n]
assent run progress <run-uuid> --done n --total m [--label l]
assent run finish <run-uuid> (--exit-code n | --status ok|fail|deferred) [--summary s] [--log-file path] [--log-tail-bytes n]
    [--task task-uuid] [--result-json path|-] [--done n] [--skipped n] [--needs-you n] [--failed n]
    [--retry-at when]
    [--issue-reason needs_action|recovery_exhausted|deadline_at_risk --impact text --action-needed text]
assent run defer <run-uuid> --retry-at when

• run progress shows progress on the phone as a Live Activity.
• run finish records how the run ended. With --task, the counts come from that task's item results. --retry-at is only allowed with --status deferred.
• --issue-reason, --impact and --action-needed go together and raise an action for you. They are not allowed with ok, and each text is at most 500 characters.
• run defer shows the run as deferred until that time, for example after a usage limit.

AsksCopy Anchor Link

assent ask --title t [--kind approve|todo|pay|login|code|reply] [--detail d] [--url u] [--draft text | --draft-file path|-]
    [--action id:label[:primary|secondary|danger]]... [--item id:title[:unselected]]...
    [--item-json path|-] [--recommend item-id]... [--reason item-id:text]... [--badge item-id:label[:tone]]...
    [--link item-id:label:url]... [--why text] [--field key:label[:type]:value]...
    [--attach item-id:path]...
    [--group key:title] [--conflict-on field-key]... [--total-of field-key] [--decline-action action-id]
    [--rule-action name] [--target t]
    [--due when] [--remind when] [--dedupe key] [--wait [--timeout seconds] [--interval seconds] [--no-pickup]]
    [--question text] [--answer-type yes_no|choice|text|number|done] [--effort minutes] [--series key]
    [--idempotency-key uuid] [--allow-duplicate]
assent attach <path> [--name n]
assent answers
assent picked-up <task-uuid>

• ask asks you. The kind defaults to approve. Asks covers every kind and option.
• attach uploads a file (pdf, png, jpeg, gif, webp, txt or md, at most 10 MB) and prints its uuid, once you turn attachments on for this agent.
• answers lists your answered asks that are not picked up yet.
• picked-up marks an answer as acted on, so it is never delivered again.

To-dosCopy Anchor Link

assent task add --title t --why text [--detail d] [--url u] [--due when] [--remind when] [--dedupe key]
    [--project project-uuid [--track name]] [--effort minutes] [--series key] [--idempotency-key uuid] [--allow-duplicate]
assent task resolve <task-uuid> [--withdraw] [--note text]
assent task update <task-uuid> [--due when|none] [--remind when|none]
assent task get <task-uuid>
assent task item-result <task-uuid> <item-id> done|skipped|needs_you|failed [--reason r] [--url u]
assent task item-status <task-uuid> <item-id>

• task add adds a to-do for you.
• task resolve closes your own ask once the work is done, or withdraws it with --withdraw. Its reminders stop.
• task update changes the due or reminder time of a task this agent created. none clears it.
• task item-result reports each item as it finishes. The --url must start with http:// or https://.
• task item-status prints go, held, withdrawn, not_selected or the recorded outcome for an item.

Notes, links and memoryCopy Anchor Link

assent note --title t (--content text | --content-file path | --content-file -) [--tag t]... [--run run-uuid]
assent note update <note-uuid> [--title t] [--content text | --content-file path | --content-file -] [--tag t]...
assent link --from type:uuid --to type:uuid [--relation produced|about|blocks|related]
assent memory get

• note writes a note you see under the agent's name. --content-file - reads stdin.
• link links two items. The types are note, task, run and agent, and the relation defaults to related.
• memory get reads the pinned memory notes you shared with this agent.

LocksCopy Anchor Link

assent lock acquire <resource> [--ttl minutes] [--wait seconds] [--interval seconds]
assent lock release <resource> [--token t]

A shared lock, for example deploy:web, keeps two agents off the same resource. The lock lasts --ttl minutes (default 30). --wait keeps trying for that many seconds, every --interval seconds (default 15). If the lock is still held, the command exits with 3. lock release uses the token saved when the lock was taken, or --token.

assent lock acquire deploy:web --ttl 45 --wait 90 && deploy; assent lock release deploy:web

Hand-offsCopy Anchor Link

assent handoff (--to <agent name> | --to-uuid <agent uuid>) --title t [--detail d] [--run run-uuid]
assent handoffs
assent handoffs done <task-uuid>

Hand work to another of your agents, list the open hand-offs other agents gave this one, and mark one as done.

Projects and plansCopy Anchor Link

assent project get <project-uuid>
assent project overview <project-uuid>
assent plan create --file path|- [--idempotency-key uuid]
assent plan get <plan-uuid>
assent plan sessions <plan-uuid> --file path|-

• project get and project overview read a project you linked this agent to: progress, tracks, milestones, this week and overdue.
• plan create takes JSON { title, summary?, tracks: [{key,title}], sessions: [{key,trackKey,title,dueAt,detail?,sessionMinutes?,habitKey?,url?}] }, with at most 1000 sessions.
• plan sessions takes JSON { sessions: [{key, dueAt?, title?, detail?, status?: open|done|cancelled}] }, with at most 500 sessions.

Rules and the Claude Code hookCopy Anchor Link

assent rules check --action name [--target t] [--summary s]
assent rules list
assent rules add --deny --action pattern [--target pattern] [--reason r] [--expires 1d|7d|30d|none]
assent rules remove <rule-uuid>
assent hook pre-tool-use

rules check exits 0 for allow, 10 for deny and 11 for ask. Agents can only add deny rules for themselves. Rules explains how rules match and how to set up the hook.

Exit codesCopy Anchor Link

Scripts should treat any exit code other than 0, 3 for locks, and 10 or 11 from rules check as "Assent unavailable, carry on as before".

PrivacyCopy Anchor Link

run finish redacts emails, tokens, keys, phone numbers and home paths from the summary and log tail before sending. note and note update redact the title and content the same way, and ask and task add redact the title and detail. A --url link and a reply draft are sent as given. Never pass passwords, card or bank details to any command: pay and login asks carry only a link.