CLI: Interact

Run

Send a single prompt to a deployed agent and stream back the execution trace:

valet run <prompt> [-a <agent>] [--org <org>] [--json] [--timeout <duration>]

Creates an ephemeral session, runs the agent loop, and displays text output, tool calls, and timing. The agent is determined by the -a/--agent flag or the linked agent in the current directory. Useful for testing agents, scripting, and programmatic access. Use --timeout to set the maximum execution time (default 10m).

$ valet run --agent my-agent "what is 2+2"
> what is 2+2

[tool] Calculator({"expression":"2+2"})
[tool] → 4

The answer is 4.

elapsed: 5s

Use --json for machine-readable newline-delimited JSON events. Each line is a JSON object with a type field: text_delta (a chunk of the reply), system_notice (an informational runtime notice), and complete (the run finished, with elapsed_ms).

Console

Start a REPL session with an agent:

valet console [-a <agent>] [--org <org>] [--resume <session-id>]

Opens a REPL-style session connected to the agent via the gateway's console channel. If the agent is still starting, waits for it to become ready before opening the session.

Resuming a prior session

valet console --resume <session-id> -a <agent>

Continues an existing session instead of starting a fresh one; the CLI verifies the session exists before opening the REPL, and the agent picks up where it left off.

Token status line

After each turn, the console prints a token usage summary in the format:

[tokens: in=N out=N cache_read=N cache_write=N total=N]

Logs

Show recent log records from an agent:

valet logs [-a <agent>] [-n <num>] [-f] [--org <org>]

By default, prints the last 100 historical log lines and exits. Use -n to change the number of lines or -n 0 to skip history entirely. Pass -f/--follow to keep the stream open and tail live log records until interrupted with Ctrl+C.

valet logs -a my-agent           # last 100 lines, then exit
valet logs -a my-agent -n 10     # last 10 lines
valet logs -a my-agent -n 1000 -f  # up to 1000 lines, then tail live
valet logs -a my-agent -n 0 -f   # live only, no history

Log format

Each log line is formatted as timestamp source process level message [key=value ...]. Structured attributes — tool names, arguments, token counts — appear after the message as sorted key=value pairs. Values containing spaces are quoted.

2026-02-28T00:58:32Z agent web.1 INFO tool_execute_start tool=bash
2026-02-28T00:58:33Z agent web.1 INFO tool_execute_done duration=1.2s tool=bash

Processes

List all processes for a deployed agent:

valet ps [-a <agent>] [--org <org>]

Shows each process with its current state, uptime, release version, and container ID. The uptime column uses a compact duration format: 3h22m, 1d4h22m. Durations of 24 hours or more are expressed in days.

Processes can show the following states: up, starting, pending, idle, crashed, down. An idle process has been automatically shut down after a period of inactivity and will wake when traffic arrives.

Restart processes

valet ps restart [-a <agent>] [--org <org>]

Restarts all processes for a deployed agent by replacing their containers using the current release. This is useful for picking up changed environment variables or recovering from a stuck state without deploying a new release.

• A restart cuts in-flight conversations immediately — unlike a deploy, which lets a busy container finish its work before replacing it. That forcefulness is the point: it is the escape hatch for a wedged agent.

Scale processes

valet ps scale changes an agent's model or process count, and an app's per-type process counts. See Agents and Apps for details. Artifacts have no processes and cannot be scaled.