Vicoa CLI

Vicoa CLI

The vicoa command lets a coding agent operate the user's Vicoa account on their behalf: their agent sessions (across every machine), their task backlog, and their scheduled automations.

Every management subcommand (session, task, project, label, automation, and ls) takes --json for machine-parseable output — always pass --json when you need to read a field programmatically, and parse it rather than scraping the table.

Auth

session, task, project, label, and automation resolve the API key in this order and never open a browser (they fail fast so an agent isn't blocked):

1. --api-key <key> flag
2. VICOA_API_KEY environment variable
3. stored credential ~/.vicoa/credentials.json (the write_key field)

If none is found, or a call returns 401, tell the user to run vicoa --auth (first-time browser sign-in) or vicoa --reauth (refresh an expired key) — these open a browser, so never run them yourself on the user's behalf; ask the user to. They save the key to ~/.vicoa/credentials.json.

Requests hit the agent-facing server https://agents.vicoa.ai by default. For a self-hosted deployment, point the CLI at your own server with --base-url <url> on any subcommand, or once for the shell with VICOA_API_URL (browser sign-in follows VICOA_AUTH_URL).

Safety & side effects

Inspect before you mutate. The read verbs (vicoa ls, vicoa session ls/get, vicoa task ls/get/comments, vicoa project ls/get, vicoa label ls, vicoa automation ls/get/runs) are safe and free — run them first to get the exact id and current state. These verbs change real state or start real work, so confirm intent before running them:

• task create/update/delete/comment — edits the user's backlog. A comment is visible to the user immediately in the web/mobile task detail. task update takes several task refs and applies the same change to each, so a wrong filter edits a lot at once. session update --task flips the linked task's status to follow the session (a running session ⇒ in_progress, a finished one ⇒ done), but never over a status someone set: mark your task blocked with task update and it stays blocked after the session ends.
• session share — mints a link that serves the session's transcript to anyone who has the URL. Publishing a transcript is not reversible in the "nobody saw it" sense; confirm first, and pass --audience authenticated when the user means "a teammate" rather than "the internet". session unshare --all revokes every live link.
• automation create/update/delete — an enabled automation will fire on its schedule and dispatch a real agent session. Create with --disabled if you only want to stage it.
• vicoa / vicoa codex / vicoa daemon / vicoa headless / vicoa session start — start real processes and register sessions. session start spends tokens on a machine that may not be the one you are on.
• vicoa stop [sessions|all|<id>] — kills live agents; don't stop sessions you didn't start without confirming. Never stop a session as automatic cleanup — including sessions you started this turn (e.g. a headless smoke-test or a session you launched to demo something). Stop only when the user explicitly asks. Otherwise leave it running; an idle session simply sits in AWAITING_INPUT and costs nothing until continued.

delete prompts [y/N]; run non-interactively without -y and it aborts rather than guessing. Pass -y/--yes only when the user has confirmed.

When to use each

vicoa ls reads local OS processes; vicoa session ls reads the backend. Use session ls for anything that isn't "processes alive on this box."

Sessions

# Agents running on THIS machine (DAEMON + TUI sections)
vicoa ls
vicoa ls --json

# Every session the user owns, across machines and history
vicoa session ls                     # newest 50
vicoa session ls --active --limit 20 # only still-running
vicoa session ls --since 7d          # started in the last week
vicoa session ls --since 2026-09-20 --until yesterday
vicoa session ls --rate-limited      # only sessions blocked by a rate limit (adds a RESET column)
vicoa session ls --limit 50 --offset 50   # page back through history
vicoa session ls --json

# Inspect one session + its transcript (the full id `session ls` prints)
vicoa session get <SESSION_ID>       # last 50 messages, clean chat view
vicoa session get <SESSION_ID> --all # full transcript
vicoa session get <SESSION_ID> --all --role user # only what the human asked for
vicoa session get <SESSION_ID> --full # + timestamps, emails, control msgs, tool payloads
vicoa session get <SESSION_ID> --json # {"instance": {...}, "messages": [...]}

# Rename a session / link it to a task (task status then follows the session)
vicoa session update <SESSION_ID> --title "Refactor auth"
vicoa session update <SESSION_ID> --task <TASK_UUID>
vicoa session update <SESSION_ID> --unlink-task
vicoa session update <SESSION_ID> --project VIC  # file under a project (`none` = No project)

# Send input into a running session (delivered to the agent; flips it ACTIVE)
vicoa session message <SESSION_ID> "run the tests and fix failures"
vicoa session continue <SESSION_ID>  # sugar: sends the literal "continue"

--since / --until take a date (2026-09-20, local midnight), a datetime, an age (30m / 24h / 7d / 2w), or today / yesterday, and filter on started_at. A bare date on --until includes that whole day.

--rate-limited returns only sessions a time-window rate limit is currently blocking; each carries rate_limited: true and rate_limit_resets_at (also the RESET column / a field in --json). A session is blocked until that instant — session continue before it just re-hits the wall. The flag clears itself once the session runs a turn under the limit again. If the target machine is offline, session message/continue fails (retry once it's back). When --rate-limited runs inside an automation-spawned session, it hides that automation's own sessions (so the auto-continue automation below can't flag-and-continue its own runs) — a different automation's rate-limited runs, and a manual session ls, still see everything.

Moving a session to a worktree

Vicoa files a session under the folder it started in. If the session creates or switches to a git worktree mid-flight, re-file it or the app keeps showing (and resuming) it under the original checkout:

vicoa session update "$VICOA_AGENT_INSTANCE_ID" --worktree <branch>

<branch> is the branch checked out in the target worktree (pass the main checkout's branch to move it back). It is resolved with local git, so run it on the machine the session lives on. The agent keeps running where it is; only the sidebar group and the next resume follow.

Starting a session

Locally, in this terminal:

vicoa                      # Claude Code (default agent)
vicoa codex                # Codex
vicoa opencode             # OpenCode
vicoa --agent amp          # any other supported agent
vicoa --name "Fix CI" --task <TASK_UUID>   # named, linked to a task
vicoa --resume <SESSION_ID>                # resume a previous session
vicoa daemon               # background daemon: accept remote/scheduled spawns

Or on any machine running a daemon — the CLI equivalent of the dashboard's "New Session":

vicoa session start --list-machines
vicoa session start --machine <id|name> --dir ~/code/app \
  --agent claude --prompt "Triage the failing tests" --wait

--dir is required — there is no default working directory. --machine defaults to this host's daemon and accepts a full id or a display-name/hostname substring. Every agent except amp can be spawned this way; amp only runs from a local vicoa --agent amp.

Match the session you're in

session start does not inherit anything from you. --agent falls back to claude and model / effort / permission-mode to that agent's defaults, however the session running this command is configured. So a Codex session on high reasoning that shells out to a bare vicoa session start silently gets a default-model Claude.

Unless the user asked for something different, start the new session as a copy of this one — read your own config and pass it through:

CFG=$(vicoa session get "$VICOA_AGENT_INSTANCE_ID" --json --limit 1 \
  | jq -r '.instance.session_config')
vicoa session start --dir "$PWD" \
  --agent          "$(jq -rn --argjson c "$CFG" '$c.agent')" \
  --model          "$(jq -rn --argjson c "$CFG" '$c.current_model // $c.model')" \
  --effort         "$(jq -rn --argjson c "$CFG" '$c.thinking_effort // $c.reasoning_effort // empty')" \
  --permission-mode "$(jq -rn --argjson c "$CFG" '$c.permission_mode // empty')"

Three things to get right when reading that payload:

• The agent id is session_config.agent (claude, codex). The sibling agent_type_name is a display label — it reads claude code on most rows, which is not a value --agent accepts.
• Prefer current_model over model. model is what the session was spawned with; current_model is what it is running now, and the two diverge the moment anyone switches model mid-session.
• Don't carry settings across a different agent. Model slugs, efforts, and permission modes are per-agent vocabularies — if the user asked for a different agent, pass only --agent and let the rest default. A Claude model slug handed to Codex is worse than no inheritance at all.

Omit a flag whose value came back empty rather than passing an empty string. --effort only applies to claude and codex; for other agents it's ignored with a warning.

Stopping:

vicoa stop                 # stop the local background daemon (prompts)
vicoa stop sessions -y     # stop all local agent sessions, no prompt
vicoa stop <SESSION_ID>    # stop one session by its full id (from `vicoa ls`)

Share links

vicoa session share                       # the session this runs in
vicoa session share <SESSION_ID> --expires 7 # public link, gone in a week
vicoa session share <SESSION_ID> --audience authenticated --show-branch
vicoa session share <SESSION_ID> --list   # existing live links
vicoa session unshare <SESSION_ID> --all  # revoke

On success share prints only the URL, so it drops straight into a $(…) — gh pr comment 123 --body "Session: $(vicoa session share)". The link is public by default and the owner's name is hidden unless --show-owner. Re-running share reuses an equivalent live link rather than minting a second one (--new forces a fresh one; --expires always mints a new link). unshare with neither --link nor --all just lists the live links and revokes nothing.

Tasks

Statuses: backlog todo in_progress in_review done blocked cancelled Priorities: urgent high medium low none

vicoa task ls                                  # all tasks
vicoa task ls --status todo --priority high --json
vicoa task ls --project VIC --label bug        # by project and label
vicoa task ls --project none                   # the unfiled ones
vicoa task get VIC-42                          # full detail

vicoa task create "Fix the flaky login test"
vicoa task create "Ship pricing page" --priority high --status todo \
  --project VIC --label design \
  --description "Localize copy first" --due 2026-08-25

vicoa task update VIC-42 --status in_progress
vicoa task update VIC-42 --priority urgent --title "New title"
vicoa task update VIC-42 VIC-43 VIC-44 --status done   # same change to each
vicoa task update VIC-42 --add-label regression        # keeps existing labels

vicoa task delete VIC-42 -y                    # -y skips the confirm prompt

create defaults to status=backlog, priority=none, and No project unless --project is given. update changes only the flags you pass. Moving a task between projects reassigns its identifier (the CLI prints VIC-20 → VIC2-2).

Refer to a task by its identifier. VIC-42 — the thing shown in the KEY column of task ls, in the task-detail header, and in what the user says out loud — works everywhere a task reference is taken: the positional argument on get/update/delete/comment/comments, and --parent. A full UUID still works too. Prefer the identifier: it is the only handle you and the user both have. Matching is case-insensitive.

Not every task has one: a task filed under No project has no identifier (moving a task to none drops it), and so does a task created before identifiers shipped. Both print — in the KEY column — use the UUID. (vicoa --task and session update --task always want the UUID.)

Projects and labels

vicoa project ls                  # KEY, NAME, ID — what --project accepts
vicoa project ls --include-archived
vicoa project get VIC

vicoa label ls                    # the names --label accepts
vicoa label create regression --color '#ef4444'

--project takes a key (VIC), a name, an id, or none for No project. Labels are one vocabulary per account, shared across projects — --label on task ls is repeatable and every one must match; on task update, --label sets the list while --add-label / --remove-label adjust it.