CLI Commands

Reference for the Vicoa CLI commands that list and stop running agent sessions on a machine.

A machine can have two kinds of session running at once:

Daemon sessions — headless agents the vicoa daemon started in response to a remote "New Session" request from the mobile app or web dashboard.
TUI sessions — interactive agents you started yourself in a terminal with vicoa, vicoa codex, or vicoa opencode.

Pre-requisite: Vicoa CLI version > 1.4.1

vicoa --version 
# Make sure it is > 1.4.1

vicoa ls

List the active agent instances on the current machine, grouped by kind.

vicoa ls

DAEMON SESSIONS (2)
  ID           AGENT      PID      AGE      PROJECT
  -------------------------------------------------
  7d4577a7     claude     10573    1d       ~/projects/my-app
  abcbe849     codex      74527    3h       ~/projects/api

TUI SESSIONS (1)
  ID           AGENT      PID      AGE      PROJECT
  -------------------------------------------------
  pid:3415     claude     3415     2h       —

Columns:

ID — the first 8 characters of the session ID. TUI sessions show pid:<n> instead, since their session ID isn't visible to vicoa ls.
AGENT — claude, codex, opencode, or amp.
PID — the operating-system process ID.
AGE — how long the session has been running.
PROJECT — the working directory (— when not detectable).

For scripting, output raw JSON instead of the table:

vicoa ls --json

Works on macOS, Linux, and Windows.

vicoa stop

Stop the daemon, the daemon's headless sessions, or both. Every vicoa stop command asks for confirmation before doing anything.

vicoa stop daemon

Stop the background daemon. Any headless sessions it started keep running.

vicoa stop
# or, equivalently
vicoa stop daemon

Stop the Vicoa daemon for https://agents.vicoa.ai (pid 1234)? [y/N]

vicoa stop with no argument defaults to daemon.

If you run multiple daemons on the same machine (one per --base-url), vicoa stop daemon stops all of them. The prompt lists each one so you can see what's about to be terminated:

Stop 2 Vicoa daemon(s)?
  - https://agents.vicoa.ai (pid 12345)
  - https://staging.vicoa.example (pid 67890)
[y/N]

To target just one daemon, pass the same --base-url you used to start it:

vicoa stop daemon --base-url https://staging.vicoa.example

vicoa stop sessions

Stop every headless session the daemon started. The daemon itself keeps running.

vicoa stop sessions

Stop 3 headless session(s)? [y/N]

Limit it to one agent type with --agent:

vicoa stop sessions --agent claude

Valid values are claude, codex, opencode, and amp.

Each session is asked to shut down gracefully first; if it doesn't exit within a short grace period it is force-stopped. Stopped sessions are marked with a terminal status in the dashboard.

vicoa stop <session-id>

Stop one specific session. Use the 8-character ID prefix shown in vicoa ls, or the full UUID:

vicoa ls
# DAEMON SESSIONS (2)
#   ID           AGENT      PID      AGE      PROJECT
#   -------------------------------------------------
#   7d4577a7     claude     10573    1d       ~/projects/my-app
#   abcbe849     codex      74527    3h       ~/projects/api

vicoa stop 7d4577a7

Stop session 7d4577a7? [y/N] y
  ✓ 7d4577a7 (claude, pid=10573) — Stopped

If the prefix matches more than one session, all matches are listed and stopped together after a single confirmation. Pass the full UUID to disambiguate.

vicoa stop all

Stop the headless sessions first, then the daemon.

vicoa stop all

Skipping confirmation

Pass -y (or --yes) to skip the confirmation prompt — useful in scripts.

vicoa stop sessions --agent codex --yes

vicoa disconnect

Alias for vicoa stop daemon. Stops only the daemon.

vicoa disconnect

Start a Remote Session — how vicoa daemon and remote sessions work.
Troubleshooting — common issues with the daemon and sessions.

On this page