CLI Commands

The T-Ex LLM command is the terminal front door to your T-Ex LLM account. From any machine you can:

• Start, resume, and stop agent sessions (Claude Code, Codex, OpenCode, and more).
• List and inspect every session you own — across machines, including finished ones — and read their message transcripts.
• Manage your task backlog — create, update, move, label, and close tasks without leaving the terminal; list your projects and labels.
• Share a session — mint a public link to a transcript (for a pull request, a teammate) and revoke it again.
• Schedule automations — saved prompts that fire an agent session on a recurring schedule.

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

• Daemon sessions — headless agents the T-Ex LLM 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 T-Ex LLM, T-Ex LLM codex, or T-Ex LLM opencode.

Keep the CLI current. Install or upgrade with npm, and check your version before using the newer session, task, and automation commands:

npm i -g @vicoa/cli@latest
T-Ex LLM --version

T-Ex LLM ls and T-Ex LLM stop require CLI 1.4.1 or newer.

Authentication

Every command that talks to the backend needs an API key. The management commands (session, task, automation, and ls) resolve it in this order and never open a browser — so a script is never left hanging on a login prompt:

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

If you don't have a stored key yet, sign in once:

T-Ex LLM --auth      # first-time sign-in (opens a browser)
T-Ex LLM --reauth    # refresh an expired or invalid key (opens a browser)

Both save the key to ~/.vicoa/credentials.json, so subsequent commands pick it up automatically. If a command returns 401 Authentication failed, your key has expired — run T-Ex LLM --reauth.

Requests go to the agent-facing server https://agents.vicoa.texllm.com by default. Point any command at a different backend with --base-url.

Starting a session

Running T-Ex LLM with no subcommand starts an interactive agent in your terminal and registers it with your account, so it shows up in the mobile app and web dashboard.

T-Ex LLM                # Claude Code (the default agent)
T-Ex LLM claude         # Claude Code, explicitly
T-Ex LLM codex          # Codex
T-Ex LLM opencode       # OpenCode
T-Ex LLM --agent amp    # Amp

The --agent flag accepts claude, amp, codex, opencode, cursor, gemini, copilot, kimi, hermes, pi, omp (Oh My Pi), and antigravity.

Common launch flags

# Start a named session linked to a task
T-Ex LLM --name "Refactor auth" --task 5f2c9d1e-...-full-uuid

# Resume where you left off
T-Ex LLM --resume 3f9c1a2b-...-full-uuid

# Make Codex your default agent for future bare `T-Ex LLM` runs
T-Ex LLM --set-default codex

T-Ex LLM daemon

Start the background daemon. It registers this machine with your account and accepts remote and scheduled session spawns from the mobile app, web dashboard, and automations. Leave it running.

T-Ex LLM daemon

Starting a session with T-Ex LLM auto-starts the daemon if it isn't already running (unless you pass --no-daemon). See Start a Remote Session for the full remote-session walkthrough.

T-Ex LLM headless

Start a background agent with no local terminal UI, driven entirely from the web or mobile dashboard.

T-Ex LLM headless --agent codex --prompt "Run the test suite and summarize failures"

T-Ex LLM headless vs T-Ex LLM session start: headless starts a background agent on this machine, right here. T-Ex LLM session start asks the backend to spawn one on any of your registered machines (including this one) — the terminal equivalent of the dashboard's "New Session". Reach for session start to launch a session on a different box, or when you want the same machine/agent/model picker the apps use.

T-Ex LLM ls

List the active agent instances on the current machine, grouped by kind. This reads local OS processes — it only sees agents running on this box.

T-Ex LLM ls

DAEMON SESSIONS (2)
  AGENT      NAME             PROJECT    PID      AGE   ID
  ------------------------------------------------------------------------------------------
  claude     Refactor auth    my-app     10573    1d    7d4577a7-2c1e-4b8a-9f3d-5e6a7b8c9d01
  codex      —                api        74527    3h    abcbe849-1f2e-4d3c-8b7a-6e5f4d3c2b10

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

Columns:

• AGENT — claude, codex, opencode, or amp.
• NAME — the session title, when it has one.
• PROJECT — the working directory (— when not detectable).
• PID — the operating-system process ID.
• AGE — how long the session has been running.
• ID — the full session ID, the form every command takes. TUI sessions show pid:<n> instead, since their session ID isn't visible to T-Ex LLM ls.

For scripting, output raw JSON instead of the table:

T-Ex LLM ls --json

Works on macOS, Linux, and Windows.

T-Ex LLM ls vs T-Ex LLM session ls: T-Ex LLM ls lists OS processes on this machine only. To see every session you own — across all machines, including cloud- or mobile-started and finished ones — use T-Ex LLM session ls below.

T-Ex LLM session

The session commands talk to the backend, so they cover every session you own regardless of which machine started it. The read verbs (ls, get) are safe to run anytime; start, update, message, and continue change state or start real work.

T-Ex LLM session start

Start a new session on one of your machines — the terminal equivalent of the desktop/web "New Session" composer. It picks a machine, directory, agent, and model/config, then hands the target machine's daemon a spawn request over REST (the same spawn path the apps drive). The session runs headless on that machine and streams to the mobile app and web dashboard, just like a remote session started from the UI.

# Start Claude Code on this host's daemon, in a directory
T-Ex LLM session start --dir ~/projects/my-app

# Pick a machine by name/hostname substring; name it and kick off with a prompt
T-Ex LLM session start --machine laptop --dir ~/projects/api \
  --name "Fix CI" --prompt "Run the test suite and fix the failures"

# Codex with a model + reasoning effort, and block until it's actually running
T-Ex LLM session start --dir ~/projects/api \
  --agent codex --model gpt-5.5 --effort medium --wait

T-Ex LLM session start needs the target machine's daemon running. The request is only picked up once that machine's T-Ex LLM daemon is connected. If the daemon looks offline, start refuses by default — pass --allow-offline to queue the request until the machine next reconnects.

Where it runs

What to run

Kick-off & discovery

Discover what's available before you start:

T-Ex LLM session start --list-machines               # which machines can run a session
T-Ex LLM session start --list-models                 # every agent's models/efforts/modes
T-Ex LLM session start --list-models --agent codex    # just Codex's options

session start returns immediately with the new session id (the daemon launches it out of band), then points you at follow-ups:

Started claude session on Laptop in ~/projects/api — session inst-123.
Track it with `T-Ex LLM session get inst-123` or send input with `T-Ex LLM session message inst-123 '...'`.

Add --wait when you want the command to block until the session is actually ACTIVE (or surfaces the error the daemon reported) instead of returning as soon as the request is accepted.

T-Ex LLM session ls

List your sessions, newest first.

T-Ex LLM session ls                      # newest 50
T-Ex LLM session ls --active --limit 20  # only still-running, cap at 20
T-Ex LLM session ls --rate-limited       # only sessions currently blocked by a rate limit
T-Ex LLM session ls --since 24h          # started in the last day
T-Ex LLM session ls --since 2026-09-15 --until 2026-09-20   # the 15th through the 20th
T-Ex LLM session ls --since yesterday --until yesterday     # all of yesterday
T-Ex LLM session ls --limit 100 --offset 100               # the second page of 100
T-Ex LLM session ls --json

WHEN accepts a date (2026-09-20), a datetime (2026-09-20T14:30, optionally with Z or an offset like +08:00), today / yesterday, or an age counted back from now (30m, 24h, 7d, 2w). Times without an offset are your local time, the same zone the STARTED column prints in. A bare date on --until includes that whole day, so --since 2026-09-20 --until 2026-09-20 is exactly the 20th. The window filters on when each session started, and total in --json counts the window.

Columns: AGENT, MODEL, STATUS, NAME, PROJECT, MSGS, STARTED, ID (the full session ID).

T-Ex LLM session get

Print one session's details and its message transcript. Every session command takes the full session ID that T-Ex LLM session ls prints. Short prefixes are not accepted, since one that names the right session today can name another after a delete.

T-Ex LLM session get <SESSION_ID>        # last 50 messages, clean chat view
T-Ex LLM session get <SESSION_ID> --all  # the full transcript
T-Ex LLM session get <SESSION_ID> --full # everything: timestamps, emails, control msgs, tool payloads
T-Ex LLM session get <SESSION_ID> --json # {"instance": {...}, "messages": [...]}
T-Ex LLM session get <SESSION_ID> --role user --all # only your messages, whole history

By default session get prints a clean chat log: tool-use header lines appear, but tool payloads, in-band control messages, timestamps, and sender emails are hidden. A footer reports how many messages and payloads were suppressed. Add flags to reveal what you need:

--role filters after the fetch. --limit counts messages of every sender, then --role narrows what's shown — so a plain --role user can surface only a handful from the fetched page. Pair it with --all to filter over the whole history. When the pre-filter limit hides messages, the text view prints a note pointing you at --all.

T-Ex LLM session update

Rename a session, link it to a task, or move it to a worktree.

T-Ex LLM session update <SESSION_ID> --title "Refactor auth"
T-Ex LLM session update <SESSION_ID> --task 5f2c9d1e-...-full-uuid
T-Ex LLM session update <SESSION_ID> --unlink-task
T-Ex LLM session update <SESSION_ID> --worktree feat/auth
T-Ex LLM session update <SESSION_ID> --worktree main

Linking drives the task's status from the session's status: a running linked session flips its task to in_progress.

--worktree is for a session whose agent moved into a worktree on its own (the sidebar keeps it under the folder it was started in): the session's sidebar group and the folder its next resume launches in follow the new checkout, while the running agent is left where it is. A session started in a subfolder of the repo lands in the same subfolder of the target. The worktree is resolved with git worktree list on this machine, so run it where the session lives; the name is the checked-out branch (the label the sidebar shows), or the directory name for a detached checkout.

T-Ex LLM session message

Send a message into a running session — it's delivered to the agent as user input and flips the session ACTIVE, the same as typing in the app. Pairs naturally with session start: start a session blank, then drive it with message. The id is the full session ID.

T-Ex LLM session message <SESSION_ID> "run the tests and fix any failures"

If the target machine is offline the message can't be delivered — retry once its daemon is back.

T-Ex LLM session continue

Shorthand that sends the literal text continue into a session — handy after a rate-limit window resets (see T-Ex LLM session ls --rate-limited).

T-Ex LLM session continue <SESSION_ID>

T-Ex LLM session share

Create a public link to a session's transcript and print its URL — the same link the dashboard's Share dialog makes. Built for attaching the session that produced a change to its pull request:

vicoa session share <SESSION_ID>              # → https://vicoa.texllm.com/share/<token>
vicoa session share                           # inside a Vicoa session: shares *this* session
vicoa session share --show-branch --expires 7 # show the git branch; dead after 7 days
vicoa session share <SESSION_ID> --list       # the session's live links
T-Ex LLM session share <SESSION_ID> --json       # the link record, with `url` added

# Attach the session to the PR you just opened
gh pr comment 123 --body "Session transcript: $(T-Ex LLM session share)"

On success it prints only the URL, so it drops straight into a $(…). Running it again for the same session returns the same link when an equivalent live one exists (same audience and display options, no expiry) — pass --new to mint another. With no session id it shares the session the command runs inside (VICOA_AGENT_INSTANCE_ID).

A shared page shows the transcript only: never the machine, the working directory, or session secrets. The viewer is the same page the dashboard's share links open, so what a link shows is documented there.

T-Ex LLM session unshare

Revoke a link. A revoked URL stops working everywhere it was pasted, so this never guesses which one:

T-Ex LLM session unshare <SESSION_ID> --link <LINK_ID> # one link, by its id from --list
T-Ex LLM session unshare <SESSION_ID> --all         # every live link on the session

With neither flag it prints the live links and exits without revoking anything.

T-Ex LLM stop

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

T-Ex LLM stop daemon

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

T-Ex LLM stop
# or, equivalently
T-Ex LLM stop daemon

Stop the T-Ex LLM daemon for https://agents.vicoa.texllm.com (pid 1234)? [y/N]

T-Ex LLM stop with no argument defaults to daemon.

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

Stop 2 T-Ex LLM daemon(s)?
  - https://agents.vicoa.texllm.com (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:

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

T-Ex LLM stop sessions

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

T-Ex LLM stop sessions

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

Limit it to one agent type with --agent:

T-Ex LLM 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.

T-Ex LLM stop <session-id>

Stop one specific session by the full ID shown in T-Ex LLM ls:

T-Ex LLM stop 7d4577a7-2c1e-4b8a-9f3d-5e6a7b8c9d01

Stop session 7d4577a7-2c1e-4b8a-9f3d-5e6a7b8c9d01? [y/N] y
  ✓ 7d4577a7-2c1e-4b8a-9f3d-5e6a7b8c9d01 (claude, pid=10573) — Stopped

T-Ex LLM stop all

Stop the headless sessions first, then the daemon.

T-Ex LLM stop all

Skipping confirmation

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

T-Ex LLM stop sessions --agent codex --yes

T-Ex LLM disconnect

Alias for T-Ex LLM stop daemon. Stops only the daemon.

T-Ex LLM disconnect

T-Ex LLM task

Manage your task backlog from the terminal. The read verbs (ls, get, comments) are safe; create, update, comment, and delete change your backlog.

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

# List and inspect
T-Ex LLM task ls                                   # all tasks
T-Ex LLM task ls --project VIC                     # one project, by key, name, or id
T-Ex LLM task ls --project none                    # the unfiled ones (No project)
T-Ex LLM task ls --label growth --status todo      # tagged growth AND todo
T-Ex LLM task ls --json
T-Ex LLM task get VIC-42                           # full detail

# Create
T-Ex LLM task create "Fix the flaky login test"
T-Ex LLM task create "Ship pricing page" --project VIC --priority high --status todo \
  --label growth --description "Localize copy first" --due 2026-08-25

# Update (only the flags you pass change; several refs apply the same change to each)
T-Ex LLM task update VIC-42 --status in_progress
T-Ex LLM task update VIC-42 --priority urgent --title "New title"
T-Ex LLM task update VIC-20 VIC-21 VIC-22 --project VIC2       # move three tasks
T-Ex LLM task update VIC-42 --add-label bug --remove-label growth
T-Ex LLM task update VIC-42 --label a --label b               # set the labels to exactly these

# Comment
T-Ex LLM task comment VIC-42 "Fixed — the flake was a missing await."
T-Ex LLM task comment VIC-42 - < report.md                    # body from stdin
T-Ex LLM task comments VIC-42 --activity                      # the thread + change log

# Delete (-y skips the confirm prompt)
T-Ex LLM task delete VIC-42 -y

Refer to a task by its identifier. VIC-42 — the KEY column of task ls, the header of the task page, and what you'd say out loud — works everywhere a task reference is taken: the positional argument on get/update/delete/comment/comments, and --parent. A full UUID works too. (A task filed under No project has no identifier; use its UUID. T-Ex LLM --task and session update --task still take the UUID.)

Refer to a project by its key. --project takes the project's task key (VIC, the prefix on every identifier), its name, or its id — T-Ex LLM project ls shows all three — and none for No project. Moving a task between projects reassigns its identifier (numbers are per project), and update prints the change as VIC-20 → VIC2-2. Moving a task to none drops its identifier.

Labels go by name. --label, --add-label, and --remove-label take label names (T-Ex LLM label ls); every flag repeats. On ls, several --labels mean the task must carry all of them. On update, --label replaces the whole set, while --add-label / --remove-label keep the rest.

create defaults to status=backlog, priority=none, and files under No project unless you pass --project.

Columns of task ls: KEY (identifier), STATUS, PRIO, PROJECT (name), TITLE, ID (full UUID). --json rows carry project_id and project_name.

update is a PATCH — pass at least one field, or it errors. With several refs, a ref that fails (typo, 404) is reported on stderr and the rest still run; the exit code is 1 if any failed.

T-Ex LLM project

Read-only list of your projects — where the keys and ids --project takes come from.

T-Ex LLM project ls                     # ID, KEY, NAME, PATH (this machine's checkout), TASKS (open)
T-Ex LLM project ls --include-archived
T-Ex LLM project get VIC                # by key, name, or id: details + every machine's checkout path
T-Ex LLM project ls --json

Projects are created and edited in the apps (a project appears automatically the first time a session runs in a folder). TASKS counts open tasks — everything but done and cancelled.

T-Ex LLM label

Your task-label vocabulary — one set of labels across every project, the same list as Settings → Tasks.

T-Ex LLM label ls
T-Ex LLM label create growth                    # colour picked from the name, as the web does
T-Ex LLM label create ops --color "#3b82f6"

Rename, recolour, and delete stay in the apps. create refuses a name that already exists, so --label <name> can never be ambiguous.

T-Ex LLM automation

An automation is a saved prompt + agent/model + machine/folder + schedule. The server's scheduler fires it, spawning a real agent session at the scheduled time. These commands are CRUD only — there is no "run now"; to run something immediately, start a session directly instead.

# Inspect
T-Ex LLM automation ls
T-Ex LLM automation get <AUTOMATION_UUID>
T-Ex LLM automation runs <AUTOMATION_UUID>        # run history

# Create: pass exactly one schedule + a session config
T-Ex LLM automation create "Nightly triage" \
  --prompt "Triage new GitHub issues and label them" \
  --agent claude --daily --time 22:00 --timezone America/New_York

T-Ex LLM automation create "Hourly build check" \
  --prompt "Run the build and report failures" \
  --agent codex --hourly --minute 15

# Pause, resume, edit, delete
T-Ex LLM automation update <AUTOMATION_UUID> --disable
T-Ex LLM automation update <AUTOMATION_UUID> --enable --prompt "New prompt"
T-Ex LLM automation delete <AUTOMATION_UUID> -y

Schedule

Choose exactly one schedule selector when you create an automation:

Modifiers: --time HH:MM (default 09:00, for daily/weekdays/weekly), --minute M (default 0, for hourly), and --timezone <IANA> (default UTC). On update, passing a selector re-times the automation; passing none leaves the schedule alone.

What to run

Give it a session config with the convenience flags, or a full JSON blob:

Where it runs

An automation needs a machine to run on. Run T-Ex LLM daemon on the target box first — it auto-registers and becomes the default target — or pass --machine-id. Also note automation update has no --agent flag; change the agent by replacing the whole config with --session-config-json '{"agent":"…"}'.

T-Ex LLM worktree

A repository can declare worktree setup commands in a committed .vicoa/config.json (or root T-Ex LLM.json) — copy .env files, install dependencies, link a shared database — and the daemon runs them in the background every time it creates a worktree for a new session, whichever device you started it from. T-Ex LLM worktree setup is the same run, on demand, from a terminal:

T-Ex LLM worktree setup                 # set up the worktree you're in
T-Ex LLM worktree setup ~/path/to/worktree
T-Ex LLM worktree setup --dry-run       # just list the commands
T-Ex LLM worktree setup --trust         # …and let the daemon auto-run this repo's setup from now on

// .vicoa/config.json, committed in the source repository
{
  "worktree": {
    "setup": [
      "cp \"$VICOA_ROOT_PATH/.env\" \"$VICOA_WORKTREE_PATH/.env\"",
      "pnpm install"
    ],
    "teardown": ["echo bye"]
  }
}

Each command is echoed, then run in the worktree under a login shell with $VICOA_WORKTREE_PATH, $VICOA_ROOT_PATH (the main checkout the config came from) and $VICOA_BRANCH_NAME set; the run stops at the first failure and the command's exit code is returned. The config is always read from the source repository's working tree, so a linked worktree runs the same setup as the checkout it was forked from. Use it to re-run after a failed automatic setup, to try a config while you are editing it, or — from an agent — to bring up a worktree whose setup did not run.

Trust. A cloned repository's T-Ex LLM.json can contain arbitrary shell, so the daemon only auto-runs setup for repositories you have approved on that machine (the dashboard asks the first time). Typing T-Ex LLM worktree setup yourself is that approval for one run — nothing is gated — and --trust records it for the future. The run's progress and log are what the session header's setup badge shows in the dashboard.

Machine-readable output

Every session, task, project, label, agent, and automation subcommand — plus T-Ex LLM ls — accepts --json, which emits raw JSON instead of the human-readable table. Prefer it whenever you're parsing a field in a script rather than scraping the table.

Paginated lists (session ls) come wrapped — {items, total, limit, offset, has_more} — so the page can say how much is left. Everything else (task ls, project ls, label ls) is the bare array the API returns.

T-Ex LLM session ls --active --json | jq '.items[].id'
T-Ex LLM task ls --project VIC --json | jq '.[].identifier'

The "new version available" banner goes to stderr, so it never lands in a --json pipe — don't merge streams with 2>&1 before parsing.

Errors & recovery

Related

• Start a Remote Session — how T-Ex LLM daemon and remote sessions work.
• Getting Started — install the CLI and register your first machine.
• Agents — pick between Claude Code, Codex, and OpenCode.
• Troubleshooting — common issues with the daemon and sessions.