# agentrun commands Every command of the agentrun CLI, by group. Arguments in capitals are positional; every command also takes `--base-url URL`, `--data DIR` and `--help`. A body field with one value (a string, number or boolean) is a flag of its own, and `--body` gives the whole body. A positional argument is refused when it is or holds a `.` or `..` path segment; a file's PATH keeps its slashes, and no segment of it may be empty. ## agents ### `agentrun agents archive AGENT_ID` Archive the agent: hidden from the lists, kept with its history. Route: `POST /agents/{agent_id}/archive`. ### `agentrun agents create` Create an agent home. Route: `POST /agents`. - `--idempotency-key STRING` (string): Makes a create safe to retry. The same key and body within `limits.idempotency_ttl_s` replays the first - `--note STRING` (string): What the revision changes, kept with it (GET /agents/{agent_id}/revisions). - `--body JSON|@FILE|-` (application/json, required): The whole body: inline, from a file or from stdin. The flags above win over a JSON body's fields. - `--body-type TYPE` (string): The body's type, one of application/json; any other than JSON is sent as given. ### `agentrun agents forget-sign-in AGENT_ID KEY` Forget one of the agent's saved sign-ins. Route: `DELETE /agents/{agent_id}/sign-ins/{key}`. ### `agentrun agents get AGENT_ID` One agent. Route: `GET /agents/{agent_id}`. ### `agentrun agents list` List agents. Route: `GET /agents`. - `--limit INTEGER` (integer) - `--cursor STRING` (string): `next_cursor` from the previous page. - `--archived` (boolean): true lists only archived agents; false, the default, the others. ### `agentrun agents runs AGENT_ID` The agent's runs index. Route: `GET /agents/{agent_id}/runs`. - `--limit INTEGER` (integer) - `--cursor STRING` (string): `next_cursor` from the previous page. - `--status queued|working|paused|input_required|completed|failed|cancelled` (string, one of these): Only runs with this status. ### `agentrun agents unarchive AGENT_ID` Show the archived agent in the lists again. Route: `POST /agents/{agent_id}/unarchive`. ### `agentrun agents update AGENT_ID` Replace the agent's definition. Route: `PUT /agents/{agent_id}/definition`. - `--if-match STRING` (string): The home's current ETag (`homeRevision`), as `GET /agents/{agent_id}` returned it. Required with the contract's body; this server's own body (`{definition, skills?, note?}`) may leave it out. - `--body JSON|@FILE|-` (application/json, required): The whole body: inline, from a file or from stdin. The flags above win over a JSON body's fields. - `--body-type TYPE` (string): The body's type, one of application/json; any other than JSON is sent as given. ## files ### `agentrun files create` Reserve an upload. Route: `POST /files`. - `--path STRING` (string): With the file's bytes as the body: the file's path (FilePathString). Its presence makes the body the file. - `--content-type STRING` (string): With `path`: the file's type. Absent, the request's own type when it names one (not application/octet-stream, not application/x-www-form-urlencoded), else the path's extension's, else application/octet-stream. - `--sha256 STRING` (string): With `path`: the hash the bytes must have (`422 input_invalid` at sha256 when they do not). - `--idempotency-key STRING` (string): Makes a create safe to retry. The same key and body within `limits.idempotency_ttl_s` replays the first - `--size-bytes INTEGER` (integer, required): At most `limits.max_upload_bytes`. - `--body JSON|@FILE|-` (application/json, application/octet-stream, */*, required): The whole body: inline, from a file or from stdin. The flags above win over a JSON body's fields. - `--body-type TYPE` (string): The body's type, one of application/json, application/octet-stream, */*; any other than JSON is sent as given. ### `agentrun files delete FILE_ID` Delete an upload. Route: `DELETE /files/{file_id}`. ### `agentrun files get FILE_ID` An upload's record. Route: `GET /files/{file_id}`. ### `agentrun files list` This server's uploads, newest first. Route: `GET /files`. - `--limit INTEGER` (integer) - `--cursor STRING` (string): `next_cursor` from the previous page. ### `agentrun files upload FILE_ID` Send a reserved file's bytes. Route: `PUT /files/{file_id}`. - `--body JSON|@FILE|-` (application/octet-stream, required): The whole body: inline, from a file or from stdin. The flags above win over a JSON body's fields. - `--body-type TYPE` (string): The body's type, one of application/octet-stream; any other than JSON is sent as given. ## home ### `agentrun home delete AGENT_ID PATH` Delete one file of the agent's home. Route: `DELETE /agents/{agent_id}/home/files/{path}`. PATH keeps its slashes. ### `agentrun home list AGENT_ID` Every file in the agent's home. Route: `GET /agents/{agent_id}/home/files`. ### `agentrun home read AGENT_ID PATH` One file of the agent's home, raw. Route: `GET /agents/{agent_id}/home/files/{path}`. It prints the answer's bytes as they are. PATH keeps its slashes. - `--download INTEGER` (integer): `1` forces a download. ### `agentrun home write AGENT_ID PATH` Write one file of the agent's home. Route: `PUT /agents/{agent_id}/home/files/{path}`. PATH keeps its slashes. - `--body JSON|@FILE|-` (application/octet-stream, */*, required): The whole body: inline, from a file or from stdin. The flags above win over a JSON body's fields. - `--body-type TYPE` (string): The body's type, one of application/octet-stream, */*; any other than JSON is sent as given. ## learning ### `agentrun learning get AGENT_ID` What the agent has learned: its index, notes, log of changes and counts. Route: `GET /agents/{agent_id}/learning`. ### `agentrun learning log AGENT_ID` A page of the changes on the agent's main, newest first. Route: `GET /agents/{agent_id}/learning/log`. - `--cursor STRING` (string): `next_cursor` from the previous page: opaque. - `--limit INTEGER` (integer): At most 200. ### `agentrun learning notes AGENT_ID` A page of the agent's notes. Route: `GET /agents/{agent_id}/learning/notes`. - `--cursor STRING` (string): `next_cursor` from the previous page: opaque, read at the commit the first page was. - `--limit INTEGER` (integer): At most 200. - `--status active|superseded|retired|pending` (string, one of these): Only notes with this status. ### `agentrun learning read AGENT_ID FILE` One note (or MEMORY.md, a skill's SKILL.md or a draft's file) on main, as text, with its ETag. Route: `GET /agents/{agent_id}/learning/files/{file}`. ### `agentrun learning retire AGENT_ID FILE` Retire a note, a skill or a workflow draft: out of every later run, kept in history. Route: `POST /agents/{agent_id}/learning/files/{file}/retire`. It prints the answer's bytes as they are. - `--if-match STRING` (string): The note's ETag, as a GET answered it: an edit or a retire lands only on that version, else 412. ### `agentrun learning write AGENT_ID FILE` Edit a note (If-Match) or create one (If-None-Match: *). Route: `PUT /agents/{agent_id}/learning/files/{file}`. It prints the answer's bytes as they are. - `--if-match STRING` (string): The note's ETag, as a GET answered it: an edit or a retire lands only on that version, else 412. - `--if-none-match STRING` (string): `*`: create the note, only if the name is not taken, else 412. - `--text STRING` (string, required): The note's whole text, front matter included. - `--body JSON|@FILE|-` (text/markdown, text/plain, application/json, required): The whole body: inline, from a file or from stdin. The flags above win over a JSON body's fields. - `--body-type TYPE` (string): The body's type, one of text/markdown, text/plain, application/json; any other than JSON is sent as given. ## local ### `agentrun local connect-git-hub` Start Connect GitHub: the app-manifest form the console posts to GitHub. Route: `POST /integrations/github/connect`. - `--org STRING` (string): The GitHub organization to make the App under; absent, the signed-in GitHub user. - `--body JSON|@FILE|-` (application/json): The whole body: inline, from a file or from stdin. The flags above win over a JSON body's fields. - `--body-type TYPE` (string): The body's type, one of application/json; any other than JSON is sent as given. ### `agentrun local delete-workspace-archil` Turn Mode 2 off: run folders on this server's own disk. Route: `DELETE /workspace/archil`. ### `agentrun local disconnect-git-hub` Disconnect GitHub: the App's credentials gone from this server, and every github trigger off. Route: `DELETE /integrations/github`. ### `agentrun local get-git-hub-connection` Whether a GitHub App is connected, and if so its id, slug and installations, never a secret. Route: `GET /integrations/github`. ### `agentrun local get-workspace-archil` Whether run folders are on an Archil disk (Mode 2), its settings, and whether its keys are saved. Route: `GET /workspace/archil`. ### `agentrun local git-hub-callback` Where GitHub sends the owner's browser back with the new App's code. Route: `GET /integrations/github/callback`. - `--code STRING` (string) - `--state STRING` (string) ### `agentrun local git-hub-installed` Where GitHub sends the browser once the App is installed. Route: `GET /integrations/github/installed`. - `--installation-id STRING` (string) - `--setup-action STRING` (string) - `--state STRING` (string) ### `agentrun local list-computers` Settings → Computers: the kinds of computer this server offers, each provider and whether its keys are saved. Route: `GET /computers`. ### `agentrun local receive-hook-github` Fire a GitHub trigger: a request it checks, no token. Route: `POST /hooks/github`. - `--body JSON|@FILE|-` (*/*, required): The whole body: inline, from a file or from stdin. The flags above win over a JSON body's fields. - `--body-type TYPE` (string): The body's type, one of */*; any other than JSON is sent as given. ### `agentrun local test-computer PROVIDER` Test a computer provider's account with its saved keys. Route: `POST /computers/{provider}/test`. ### `agentrun local test-workspace-archil` Test the Archil disk with its saved account key. Route: `POST /workspace/archil/test`. ## login ### `agentrun login` Check a server's token, read from stdin, and keep it with the server's address in the config file. Route: `GET /agents?limit=1, to check the token`. - `--base-url URL` (string, this CLI's own): the server's API, ending /v2 (default AGENTRUN_BASE_URL) ## logout ### `agentrun logout` Remove the config file login wrote, its address and token. Route: none, it runs on this machine. ## mcp-servers ### `agentrun mcp-servers delete NAME` Forget a saved MCP server and its credential. Route: `DELETE /settings/mcp-servers/{name}`. ### `agentrun mcp-servers get NAME` One saved MCP server; never its credential. Route: `GET /settings/mcp-servers/{name}`. ### `agentrun mcp-servers list` The remote MCP servers saved here, with their tools; never a credential. Route: `GET /settings/mcp-servers`. ### `agentrun mcp-servers oauth-client` This server's OAuth client metadata document. Route: `GET /settings/mcp-servers/oauth/client.json`. ### `agentrun mcp-servers private-hosts` The private-network hosts an MCP server's authorization server may be on. Route: `GET /settings/mcp-servers/oauth/private-hosts`. ### `agentrun mcp-servers refresh NAME` List a saved MCP server's tools again, keep them, and say what changed. Route: `POST /settings/mcp-servers/{name}/refresh`. ## revisions ### `agentrun revisions list AGENT_ID` The agent's revisions, newest first. Route: `GET /agents/{agent_id}/revisions`. - `--limit INTEGER` (integer) - `--cursor STRING` (string): `next_cursor` from the previous page. ### `agentrun revisions set-current AGENT_ID` Make one of the agent's revisions current again. Route: `POST /agents/{agent_id}/current`. - `--revision STRING` (string, required) - `--body JSON|@FILE|-` (application/json, required): The whole body: inline, from a file or from stdin. The flags above win over a JSON body's fields. - `--body-type TYPE` (string): The body's type, one of application/json; any other than JSON is sent as given. ## runs ### `agentrun runs archive RUN_ID` Archive the run: hidden from the lists, kept with its history. Route: `POST /runs/{run_id}/archive`. ### `agentrun runs cancel RUN_ID` End the run. Route: `POST /runs/{run_id}/cancel`. ### `agentrun runs create-inline-run` Start a run of an agent another system owns, given inline. Route: `POST /runs`. - `--idempotency-key STRING` (string): Makes a create safe to retry. The same key and body within `limits.idempotency_ttl_s` replays the first - `--note STRING` (string): What the version changes, kept with its revision by the version's first run (GET /agents/{agent_id}/revisions); not part of its definition. - `--effort low|medium|high` (string, one of these): How hard a run works. It sets the model's thinking level, and adds a short note on how to work right after the agent's instructions, on every harness: low answers directly, medium plans briefly and checks once, high plans each part, fills the gaps and reviews. A run started with none thinks at its agent revision's own thinking level, else the host's default, and gets no note. - `--max-cost-usd NUMBER` (number): This run's cap, for every turn of it. Default the definition's `max_cost_usd`, else the effort default. - `--quote-id STRING` (string): Run at a quote's terms. A different `effort` or `max_cost_usd` than the quote's is `409 quote_invalid`. - `--cap-mode expected|strict` (string, one of these): How the run's cap (`max_cost_usd`) prices each model request's input. `expected` (the default): the input the previous request of its conversation reported read from or written to the cache, at the cache-read price, when that request ended less than 4 minutes before; the rest of its input (the previous request's input after the cache, and what the conversation grew by since, a token a byte) at the input price, the cache write's when dearer. With no such request, all of it at that price. Output is limited to what the cap leaves, so output never passes it; a cache miss can, by at most the request's bound (its input uncached less its input expected), served as the run's `cost.overshoot_bound_usd` while it is in flight; its real cost is booked, and the timeline says so. `strict`: every input token at the input or cache-write price, the worst case: no request passes the cap, and a run pauses sooner. Only with a cap. Absent: the agent's (its definition's `cap_mode`), else expected. 422 not_allowed for a run with no cap. - `--body JSON|@FILE|-` (application/json, required): The whole body: inline, from a file or from stdin. The flags above win over a JSON body's fields. - `--body-type TYPE` (string): The body's type, one of application/json; any other than JSON is sent as given. ### `agentrun runs files RUN_ID` The files the run wrote. Route: `GET /runs/{run_id}/files`. ### `agentrun runs get RUN_ID` One run. Route: `GET /runs/{run_id}`. ### `agentrun runs graph RUN_ID` A workflow run's graph, live. Route: `GET /runs/{run_id}/graph`. ### `agentrun runs hand-back-run-computer RUN_ID` Hand the run's computer back to the agent, or answer its ask for the owner. Route: `POST /runs/{run_id}/computer/hand-back`. - `--outcome done|cancelled` (string, one of these): The answer to the agent's ask: `done` when the person did what it asked, `cancelled` when they will not. Absent: done. - `--body JSON|@FILE|-` (application/json): The whole body: inline, from a file or from stdin. The flags above win over a JSON body's fields. - `--body-type TYPE` (string): The body's type, one of application/json; any other than JSON is sent as given. ### `agentrun runs learning RUN_ID` The run's learning whole: its seed, merge, verdict, problems and cost. Route: `GET /runs/{run_id}/learning`. ### `agentrun runs learning-diff RUN_ID` What the run proposed, file by file. Route: `GET /runs/{run_id}/learning/diff`. ### `agentrun runs list` Every agent's runs, newest first. Route: `GET /runs`. - `--limit INTEGER` (integer) - `--cursor STRING` (string): `next_cursor` from the previous page. - `--agent STRING` (string): Only this agent's runs. - `--revision STRING` (string): Only runs of this revision. - `--status queued|working|paused|input_required|completed|failed|cancelled` (string, one of these): Only runs with this status. - `--archived` (boolean): true lists only archived runs; false, the default, the others. ### `agentrun runs message RUN_ID` Send the run a message. Route: `POST /runs/{run_id}/messages`. - `--idempotency-key STRING` (string): Makes a create safe to retry. The same key and body within `limits.idempotency_ttl_s` replays the first - `--content STRING` (string, required): At most `limits.max_message_chars`. Not only whitespace. - `--body JSON|@FILE|-` (application/json, required): The whole body: inline, from a file or from stdin. The flags above win over a JSON body's fields. - `--body-type TYPE` (string): The body's type, one of application/json; any other than JSON is sent as given. ### `agentrun runs pause RUN_ID` Pause a workflow run. Route: `POST /runs/{run_id}/pause`. ### `agentrun runs raise-cap RUN_ID` Raise a run's spend cap. Route: `PATCH /runs/{run_id}`. - `--max-cost-usd NUMBER` (number, required): The new cap, above the run's current cap. - `--body JSON|@FILE|-` (application/json, required): The whole body: inline, from a file or from stdin. The flags above win over a JSON body's fields. - `--body-type TYPE` (string): The body's type, one of application/json; any other than JSON is sent as given. ### `agentrun runs read-file RUN_ID PATH` One file's raw bytes. Route: `GET /runs/{run_id}/files/{path}`. It prints the answer's bytes as they are. PATH keeps its slashes. - `--download INTEGER` (integer): `1` forces a download. - `--range STRING` (string): One byte range, `bytes=-`. ### `agentrun runs resume RUN_ID` Resume a paused workflow run. Route: `POST /runs/{run_id}/resume`. ### `agentrun runs start AGENT_ID` Start a run. Route: `POST /agents/{agent_id}/runs`. - `--idempotency-key STRING` (string): Makes a create safe to retry. The same key and body within `limits.idempotency_ttl_s` replays the first - `--effort low|medium|high` (string, one of these): How hard a run works. It sets the model's thinking level, and adds a short note on how to work right after the agent's instructions, on every harness: low answers directly, medium plans briefly and checks once, high plans each part, fills the gaps and reviews. A run started with none thinks at its agent revision's own thinking level, else the host's default, and gets no note. - `--max-cost-usd NUMBER` (number): This run's cap, for every turn of it. Default the definition's `max_cost_usd`, else the effort default. - `--quote-id STRING` (string): Run at a quote's terms. A different `effort` or `max_cost_usd` than the quote's is `409 quote_invalid`. - `--cap-mode expected|strict` (string, one of these): How the run's cap (`max_cost_usd`) prices each model request's input. `expected` (the default): the input the previous request of its conversation reported read from or written to the cache, at the cache-read price, when that request ended less than 4 minutes before; the rest of its input (the previous request's input after the cache, and what the conversation grew by since, a token a byte) at the input price, the cache write's when dearer. With no such request, all of it at that price. Output is limited to what the cap leaves, so output never passes it; a cache miss can, by at most the request's bound (its input uncached less its input expected), served as the run's `cost.overshoot_bound_usd` while it is in flight; its real cost is booked, and the timeline says so. `strict`: every input token at the input or cache-write price, the worst case: no request passes the cap, and a run pauses sooner. Only with a cap. Absent: the agent's (its definition's `cap_mode`), else expected. 422 not_allowed for a run with no cap. - `--body JSON|@FILE|-` (application/json, required): The whole body: inline, from a file or from stdin. The flags above win over a JSON body's fields. - `--body-type TYPE` (string): The body's type, one of application/json; any other than JSON is sent as given. - `--wait` (boolean, this CLI's own): then wait until the run ends or waits on a person, and print it as runs wait does - `--timeout SECONDS` (number, this CLI's own): with --wait: stop waiting after this long, exit 1 (the run goes on) ### `agentrun runs stop RUN_ID` End the current turn. Route: `POST /runs/{run_id}/stop`. ### `agentrun runs take-over-run-computer RUN_ID` Take over the run's desktop or phone. Route: `POST /runs/{run_id}/computer/take-over`. - `--body JSON|@FILE|-` (application/json): The whole body: inline, from a file or from stdin. The flags above win over a JSON body's fields. - `--body-type TYPE` (string): The body's type, one of application/json; any other than JSON is sent as given. ### `agentrun runs timeline RUN_ID` The run's timeline, as a page or a stream. Route: `GET /runs/{run_id}/timeline`. - `--after INTEGER` (integer): The change cursor last applied, from `next_after` or the last SSE `id`. 0 is the start. - `--wait-ms INTEGER` (integer): JSON only. How long to hold the request for a change after `after`. - `--limit INTEGER` (integer): At most this many rows in a page (1 to 500, default 500); has_more says when another waits. - `--last-event-id STRING` (string): SSE reconnect. Same meaning as `after`, and wins over it. - `--follow` (boolean, this CLI's own): the timeline as it changes, one page per line (NDJSON), until the run ends; resumes a dropped connection ### `agentrun runs unarchive RUN_ID` Show the archived run in the lists again. Route: `POST /runs/{run_id}/unarchive`. ### `agentrun runs wait RUN_ID` Wait until the run ends or waits on a person, and print it. Route: `GET /runs/{run_id}/timeline, long-polled, then GET /runs/{run_id}`. - `--timeout SECONDS` (number, this CLI's own): stop waiting after this long, exit 1 (the run goes on) ## server ### `agentrun server capabilities` What this backend offers. Route: `GET /capabilities`. ### `agentrun server health` Whether this server can serve. Route: `GET /health`. ### `agentrun server mcp` The MCP endpoint: this API's tools, for a coding agent. Route: `POST /mcp`. - `--method STRING` (string) - `--body JSON|@FILE|-` (application/json, required): The whole body: inline, from a file or from stdin. The flags above win over a JSON body's fields. - `--body-type TYPE` (string): The body's type, one of application/json; any other than JSON is sent as given. Built from flags alone, the body also has: `jsonrpc` `"2.0"`, `id` `1`. ### `agentrun server openapi` This document. Route: `GET /openapi.json`. ## skill ### `agentrun skill install` Install this CLI's skill (agentrun-cli) for Claude Code and Codex, or into a skills directory. Route: none, it runs on this machine. - `--claude` (boolean, this CLI's own): into Claude Code's skills: ~/.claude/skills/agentrun-cli - `--codex` (boolean, this CLI's own): into ~/.agents/skills/agentrun-cli, the shared skills folder Codex reads (Cursor too) - `--dir DIR` (string, this CLI's own): into DIR/agentrun-cli (a project's .claude/skills or .agents/skills, say) ## stats ### `agentrun stats` Counts and cost over every agent and run. Route: `GET /stats`. - `--from STRING` (string): Runs started at or after this RFC 3339 date-time, to the millisecond (a finer fraction is a 400). Default no bound. - `--to STRING` (string): Runs started before this RFC 3339 date-time, to the millisecond (a finer fraction is a 400). Default no bound. - `--agent STRING` (string): One agent's runs. ## template ### `agentrun template apply TEMPLATE` Apply a template package: make its agent, with its skills, then its triggers. Route: `POST /templates/{template}/apply`. - `--idempotency-key STRING` (string): Makes a create safe to retry. The same key and body within `limits.idempotency_ttl_s` replays the first - `--body JSON|@FILE|-` (application/json, required): The whole body: inline, from a file or from stdin. The flags above win over a JSON body's fields. - `--body-type TYPE` (string): The body's type, one of application/json; any other than JSON is sent as given. ### `agentrun template eval DIR` Run a template package's eval cases as real runs of its agent and grade each run (real models cost money). Route: none, it runs on this machine. - `--case NAME` (string, this CLI's own): a case to run (repeat it); without one, every case - `--runs N` (string, this CLI's own): how many runs of each case, in place of each case's own runs - `--server URL` (string, this CLI's own): run on that server, with its token (AGENTRUN_API_KEY), instead of on a server of its own over a temp data directory - `--grader-model PROVIDER/MODEL` (string, this CLI's own): the model of the llm graders (default: the server's) - `--report FILE` (string, this CLI's own): the whole report, as JSON (a summary goes to stdout either way) - `--faux MODULE` (string, this CLI's own): answer every model request from MODULE's default export: no key, no network ### `agentrun template list` The template packages this server ships: each makes an agent, its skills and its triggers. Route: `GET /templates`. ### `agentrun template validate DIR` Check a template package folder (agent.md, skills/, rules/, evals/) as a server does before it applies one. Route: none, it runs on this machine. ## tool-keys ### `agentrun tool-keys list` The tool keys a person may save, and which are set: names only, never a value. Route: `GET /settings/tool-keys`. ## tool-settings ### `agentrun tool-settings get` The server's tool settings. Route: `GET /settings/tools`. ### `agentrun tool-settings save` Set the providers of web_search, web_fetch and browser, and each tool's permission. Route: `PUT /settings/tools`. - `--body JSON|@FILE|-` (application/json, required): The whole body: inline, from a file or from stdin. The flags above win over a JSON body's fields. - `--body-type TYPE` (string): The body's type, one of application/json; any other than JSON is sent as given. ## triggers ### `agentrun triggers create` Make a trigger: a schedule or a signed webhook that starts a capped run of an agent, or messages a run. Route: `POST /triggers`. - `--idempotency-key STRING` (string): Makes a create safe to retry. The same key and body within `limits.idempotency_ttl_s` replays the first - `--name STRING` (string): Default the trigger's id. - `--enabled` (boolean): Off, it fires nothing; on again, it goes on from now: the time it was off is skipped, never caught up. - `--catchup-window-s INTEGER` (integer) - `--max-active-runs INTEGER` (integer): For a `start_run` trigger of a pushed source (a webhook, with or without `accept`): each event starts its own run, never skipped behind the last, and this is the most of its runs active at once. A firing past it waits due and is tried again; past 20 due an event is 429 `rate_limited`. Null: a trigger with `accept` takes every run this server has room for, and one without keeps the overlap skip. A schedule or a `message_run` target is 422 with it set. A PATCH with null clears it. - `--body JSON|@FILE|-` (application/json, required): The whole body: inline, from a file or from stdin. The flags above win over a JSON body's fields. - `--body-type TYPE` (string): The body's type, one of application/json; any other than JSON is sent as given. ### `agentrun triggers delete TRIGGER_ID` Delete a trigger and its firings; the runs it started stay. Route: `DELETE /triggers/{trigger_id}`. ### `agentrun triggers fire TRIGGER_ID` Run it now: one firing per Idempotency-Key. Route: `POST /triggers/{trigger_id}/fire`. - `--idempotency-key STRING` (string, required): Required here: a retry with the same key fires once. ### `agentrun triggers firings TRIGGER_ID` The trigger's last 200 firings, newest first. Route: `GET /triggers/{trigger_id}/firings`. ### `agentrun triggers get TRIGGER_ID` One trigger. Route: `GET /triggers/{trigger_id}`. ### `agentrun triggers list` The triggers: schedules and signed webhooks that start an agent's capped runs or message a run. Route: `GET /triggers`. ### `agentrun triggers rotate-secret TRIGGER_ID` A webhook trigger's new secret, shown once; the old one signs nothing from now on. Route: `POST /triggers/{trigger_id}/secret`. ### `agentrun triggers update TRIGGER_ID` Change a trigger, or turn it off and on. Route: `PATCH /triggers/{trigger_id}`. - `--name STRING` (string): Default the trigger's id. - `--enabled` (boolean): Off, it fires nothing; on again, it goes on from now: the time it was off is skipped, never caught up. - `--catchup-window-s INTEGER` (integer) - `--max-active-runs INTEGER` (integer): For a `start_run` trigger of a pushed source (a webhook, with or without `accept`): each event starts its own run, never skipped behind the last, and this is the most of its runs active at once. A firing past it waits due and is tried again; past 20 due an event is 429 `rate_limited`. Null: a trigger with `accept` takes every run this server has room for, and one without keeps the overlap skip. A schedule or a `message_run` target is 422 with it set. A PATCH with null clears it. - `--body JSON|@FILE|-` (application/json, required): The whole body: inline, from a file or from stdin. The flags above win over a JSON body's fields. - `--body-type TYPE` (string): The body's type, one of application/json; any other than JSON is sent as given. ## usage ### `agentrun usage` Usage by meter over a period. Route: `GET /usage`. - `--from STRING` (string): Start of the period, inclusive. Default the start of this calendar month, UTC. - `--to STRING` (string): End of the period, exclusive. Default now. - `--group-by meter|agent|key|day|region` (string, one of these) ## webhook ### `agentrun webhook delete` Remove the webhook; its pending messages are dropped, the log of attempts is kept. Route: `DELETE /settings/webhook`. ### `agentrun webhook deliveries` The last 50 attempts, newest first. Route: `GET /settings/webhook/deliveries`. ### `agentrun webhook get` The webhook this server POSTs run notices to, if one is set; never its secret. Route: `GET /settings/webhook`. ### `agentrun webhook redeliver WEBHOOK_ID` Send a message of the log again, once now, under the same webhook-id and body. Route: `POST /settings/webhook/deliveries/{webhook_id}/redeliver`. ### `agentrun webhook save` Set the webhook's URL. Route: `PUT /settings/webhook`. - `--url STRING` (string, required) - `--body JSON|@FILE|-` (application/json, required): The whole body: inline, from a file or from stdin. The flags above win over a JSON body's fields. - `--body-type TYPE` (string): The body's type, one of application/json; any other than JSON is sent as given. ### `agentrun webhook test` Send a `webhook.test` message now, once, and say how it went. Route: `POST /settings/webhook/test`. ## workflows ### `agentrun workflows validate` Check a workflow definition without saving it. Route: `POST /workflows/validate`. - `--body JSON|@FILE|-` (application/json, required): The whole body: inline, from a file or from stdin. The flags above win over a JSON body's fields. - `--body-type TYPE` (string): The body's type, one of application/json; any other than JSON is sent as given.