foldrun.docs
Browse docs

Docs

CLI reference

foldrun needs no account. ANTHROPIC_API_KEY (or CLAUDE_CODE_OAUTH_TOKEN) is enough to run agents; init and check need nothing at all.

Commands
foldrun init [dir] create a workspace that runs immediately
foldrun check [dir] validate agents, flows, tools, evals, knowledge — offline
foldrun run <target> run an agent or a flow (name, or flow:name)
foldrun eval [name] one eval, or all of them
foldrun probe <model> can this model hold a tool loop here? A live check
foldrun logs [run-id] recent runs, or one run’s whole event trail
foldrun secrets set NAME store a secret — also ls, rm
foldrun deploy [dir] push a workspace into an installation
foldrun invoke <flow> start a flow on a running platform — --watch follows its trace here
foldrun open [page] the dashboard for this workspace, in the browser (runs, agents, graph, repo…)
foldrun login sign this machine in from the browser — no key to copy
foldrun logout forget this machine’s key, and revoke it if login made it
foldrun whoami who you are on the platform: account, role, which workspaces
foldrun keys ls the account’s API keys — also create <label>, revoke <id>

Options
--workspace <dir> the workspace folder (default .)
--from <template> start from a shipped template, e.g. templates/hello
--task "<text>" the instruction for a manual run
--follow logs: keep tailing a live run — locally, or on the platform with --url
--watch invoke: follow the run’s trace here as it happens; the exit code is the run’s
--print open: print the URL, do not open it
--value "<text>" secrets set: skip the prompt — careful with shell history
--account secrets: account scope rather than this workspace’s
--wait invoke: hold on and print the result
--from <n> invoke: start at step n, skipping earlier ones
--no-browser login: print the address instead of opening it
--role <r> keys create: viewer, editor (default) or admin
--for <workspace> keys create: a deploy key for one workspace; --access read or write
--local deploy: into the installation on this machine, even when signed in

Signing in

foldrun login

The terminal shows a short code and opens the dashboard on a page that asks whether this is your terminal. Say yes, and the terminal is signed in: every command after that reaches the platform without --url or --token.

What happened underneath is ordinary. Approving minted an API key at your role — labelled cli · <machine> on Settings → API keys, where it can be revoked like any other — and the CLI stored it in ~/.foldrun/credentials.json (mode 0600; FOLDRUN_HOME moves the directory). An owner’s terminal is an admin’s: a key is never an owner.

foldrun login --url https://foldrun.example.com signs in to your own installation; the last one signed in to is the default afterwards, and --url on any command picks another. foldrun login --token <key> stores a key made in the dashboard instead of opening a browser — for a machine with none, or to hold a deploy key for one workspace — after checking that it works.

foldrun whoami says who the platform thinks you are and where the credential came from. foldrun logout forgets the key and, when login made it, revokes it.

In CI, set FOLDRUN_TOKEN rather than logging in: the environment beats the file, so a job with a key in its variables never reads one from disk. foldrun keys create ci --for leads --access write makes a key that can only git push that one workspace.

Talking to a platform

deploy, invoke, secrets, logs and keys all reach a running installation:
--url <url> the platform, or FOLDRUN_URL, or where you last signed in
--token <key> an API key, or FOLDRUN_TOKEN, or the one foldrun login stored
--to <workspace> which workspace there (deploy defaults to the folder name)
--tenant <name> account to deploy into (local installations only)
--data <dir> the installation’s data directory
--commit <sha> record which commit a deploy is
--dry-run check and report, change nothing
--force deploy even while runs are in flight

check, run, eval and probe are local — they read the workspace on disk and the runs beside it. logs and deploy are local too, until a platform is named — by --url, by FOLDRUN_URL, or by having signed in (--local puts a deploy back on this machine): then it lists that workspace’s runs there, prints one run’s trail, and --follow tails a live one. open always needs a platform.

The loop, in order

foldrun check                      # after every edit. Free.
foldrun run publish --task "..."   # locally, against real models
foldrun eval                       # did the change break an agent?
foldrun deploy --url $FOLDRUN_URL  # checked again server-side before it lives
foldrun invoke publish --watch     # run it there, trace streamed here
foldrun logs --to publish-desk     # what ran there lately
foldrun open runs                  # the same, in the browser

A push to any branch other than main previews it: the platform deploys the branch’s tree to <workspace>-preview-<branch> and runs its evals there. Previews never fire on a schedule, read the source workspace’s secrets, and disappear when the branch does.