agent.run()
DOCUMENTATION / PLATFORM REFERENCE
View MarkdownSource on GitHub

Based on AgentRun release · Synced .

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=<start>-<end>.

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.