Agent commands

Deliver a turn to a connected runner, host its turns on your own machine, and read what each turn saved.

Preview

Deliver a turn to a connected runner, or host its turns on this machine. Read Connected runners for what a turn does.

puni agentDeliver turns to a connected runner, host them on your own machine, and inspect their saved work.

Command	What it does
`puni agent health`	Check that the agent service answers.
`puni agent presence`	Whether a machine of yours is hosting turns right now.
`puni agent serve`	Host new turns for your account on this machine. Shutdown tries to release unfinished work for another runner; a running turn does not switch to the backend. Restart before the turn expires to continue. With --json, parse stdout as NDJSON: raw lifecycle records arrive first, followed by a final success or error envelope when the process ends. Do not parse the whole stream as one JSON value.
`puni agent request`	Deliver a scene request to a connected runner. Without one, PUNI_RUNNER_REQUIRED refuses the turn; no server model fallback runs.
`puni agent history`	List a scene's turns: what was asked, what was answered, and the revision each one saved.
`puni agent turn`	Read one turn with its events.
`puni agent cancel`	Stop a running turn.

#`agent health`

Check that the agent service answers.

puni agent health --base-url https://puni.design

Flag	Type	Default	What it does
`--base-url`	`string`		The studio origin, such as https://puni.design. Defaults to PUNI_BASE_URL, else the one studio you are signed in to. HTTPS, except loopback.
`--auth-file`	`string`		Read and write credentials in this file instead of ~/.config/puni/credentials.json.
`--json`	`boolean`	`false`	Answer with one JSON envelope instead of the shell view. Exception: agent serve streams raw lifecycle JSON lines before its final envelope.
`--help` `-h`	`boolean`		Print the command list.

#Run `agent health`

puni agent health --base-url https://puni.design --json

#`agent presence`

Whether a machine of yours is hosting turns right now.

puni agent presence --base-url https://puni.design

Flag	Type	Default	What it does
`--base-url`	`string`		The studio origin, such as https://puni.design. Defaults to PUNI_BASE_URL, else the one studio you are signed in to. HTTPS, except loopback.
`--auth-file`	`string`		Read and write credentials in this file instead of ~/.config/puni/credentials.json.
`--json`	`boolean`	`false`	Answer with one JSON envelope instead of the shell view. Exception: agent serve streams raw lifecycle JSON lines before its final envelope.
`--help` `-h`	`boolean`		Print the command list.

#Run `agent presence`

puni agent presence --base-url https://puni.design --json

#`agent serve`

Host new turns for your account on this machine. Shutdown tries to release unfinished work for another runner; a running turn does not switch to the backend. Restart before the turn expires to continue. With --json, parse stdout as NDJSON: raw lifecycle records arrive first, followed by a final success or error envelope when the process ends. Do not parse the whole stream as one JSON value.

puni agent serve --base-url https://puni.design [--name label] [--exec command]

Flag	Type	Default	What it does
`--name`	`string`		A label kept with this runner's registration. Presence does not report it.
`--exec`	`string`		A command that receives each turn as JSON on standard input and answers on standard output.
`--base-url`	`string`		The studio origin, such as https://puni.design. Defaults to PUNI_BASE_URL, else the one studio you are signed in to. HTTPS, except loopback.
`--auth-file`	`string`		Read and write credentials in this file instead of ~/.config/puni/credentials.json.
`--json`	`boolean`	`false`	Answer with one JSON envelope instead of the shell view. Exception: agent serve streams raw lifecycle JSON lines before its final envelope.
`--help` `-h`	`boolean`		Print the command list.

#Run `agent serve`

puni agent serve --base-url https://puni.design --name my-laptop --json

#`agent request`

Ask your connected runner to change a scene and read the saved revision. Without a connected runner, the CLI exits 75 with PUNI_CONFLICT and detail.code: "PUNI_RUNNER_REQUIRED". The refusal tells you to start puni agent serve.

puni agent request PROJECT_ID --revision N --message text [--time 0] [--ids id,id] --base-url https://puni.design

Flag	Type	Default	What it does
`--revision` required	`number`		The revision you expect.
`--message` required	`string`		What to change.
`--time`	`number`	`0`	The playhead to send with the request.
`--ids`	`string`		The selection to send, comma-separated.
`--base-url`	`string`		The studio origin, such as https://puni.design. Defaults to PUNI_BASE_URL, else the one studio you are signed in to. HTTPS, except loopback.
`--auth-file`	`string`		Read and write credentials in this file instead of ~/.config/puni/credentials.json.
`--json`	`boolean`	`false`	Answer with one JSON envelope instead of the shell view. Exception: agent serve streams raw lifecycle JSON lines before its final envelope.
`--help` `-h`	`boolean`		Print the command list.

#Run `agent request`

puni agent request quiet-guest --revision 8 --message 'Make the figure wave gently.' --base-url https://puni.design --json

#`agent history`

List a scene's turns: what was asked, what was answered, and the revision each one saved.

puni agent history PROJECT_ID --base-url https://puni.design

Flag	Type	Default	What it does
`--base-url`	`string`		The studio origin, such as https://puni.design. Defaults to PUNI_BASE_URL, else the one studio you are signed in to. HTTPS, except loopback.
`--auth-file`	`string`		Read and write credentials in this file instead of ~/.config/puni/credentials.json.
`--json`	`boolean`	`false`	Answer with one JSON envelope instead of the shell view. Exception: agent serve streams raw lifecycle JSON lines before its final envelope.
`--help` `-h`	`boolean`		Print the command list.

#Run `agent history`

puni agent history quiet-guest --base-url https://puni.design --json

#`agent turn`

Read one turn with its events.

puni agent turn TURN_ID --base-url https://puni.design

Flag	Type	Default	What it does
`--base-url`	`string`		The studio origin, such as https://puni.design. Defaults to PUNI_BASE_URL, else the one studio you are signed in to. HTTPS, except loopback.
`--auth-file`	`string`		Read and write credentials in this file instead of ~/.config/puni/credentials.json.
`--json`	`boolean`	`false`	Answer with one JSON envelope instead of the shell view. Exception: agent serve streams raw lifecycle JSON lines before its final envelope.
`--help` `-h`	`boolean`		Print the command list.

#Run `agent turn`

puni agent turn trn_… --base-url https://puni.design --json

#`agent cancel`

Stop a running turn.

puni agent cancel TURN_ID --base-url https://puni.design

Flag	Type	Default	What it does
`--base-url`	`string`		The studio origin, such as https://puni.design. Defaults to PUNI_BASE_URL, else the one studio you are signed in to. HTTPS, except loopback.
`--auth-file`	`string`		Read and write credentials in this file instead of ~/.config/puni/credentials.json.
`--json`	`boolean`	`false`	Answer with one JSON envelope instead of the shell view. Exception: agent serve streams raw lifecycle JSON lines before its final envelope.
`--help` `-h`	`boolean`		Print the command list.

#Run `agent cancel`

puni agent cancel trn_… --base-url https://puni.design --json

Back to the command line index for every group.

Was this useful?

#agent health

#Run agent health

#agent presence

#Run agent presence

#agent serve

#Run agent serve

#agent request

#Run agent request

#agent history

#Run agent history

#agent turn

#Run agent turn

#agent cancel

#Run agent cancel