Command reference

The urun command surface. Run any command with --help for the authoritative flags and defaults — the terminal help is generated from the same source as the CLI itself.

Global

urun --version          # print the CLI version
urun --help             # top-level help

Most commands accept these credential flags (resolved from flag → env → saved login → default):

urun login

Save manually vended deploy credentials.

urun login [--api-key KEY] [--api-url URL] [--no-browser]

If --api-key is omitted in a TTY, the CLI prompts for it. Verifies the key and stores org_id / key_id locally. See Authentication.

urun deploy

Package and ship a Python app, polling to readiness.

urun deploy <entrypoint> [--name NAME] [--environment ENV] [--no-wait]
                         [--poll-interval 2.0] [--timeout 1800.0]

See Deploy apps.

urun run

urun run <entrypoint> [same flags as deploy]

run is an alias for deploy — same flags, same pipeline. Prefer urun deploy.

urun cancel, urun build

urun cancel <manifest> [--json]          # cancel an in-flight (queued/building) deploy
urun build cancel <manifest> [--json]    # alias of `urun cancel`
urun build purge  <manifest> [--yes] [--json]   # purge a FAILED build artifact

<manifest> is the full 64-character manifest hash printed by urun deploy, or a unique 12+ character prefix. Cancelling frees the build slot immediately; a fresh urun deploy re-queues cleanly. Only failed artifacts can be purged.

urun serve

Deploy a model from the model catalog — no app.py to write.

urun serve catalog [--json]                    # enumerate the (model, variant, GPU) matrix
urun serve <id>[:<variant>] [--gpu SPEC]       # deploy, e.g. urun serve qwen-coder:fp8 --gpu l4:1

Also accepts --name, --environment, --no-wait, --poll-interval, --timeout like urun deploy. See Serve a model.

urun demo

urun demo <app> [--function NAME] [--port N] [--no-browser]

Launch a local browser frontend for a deployed official example app (<app> is the deployed app slug, as shown by urun app list), minting a short-lived browser session JWT via your API key. uRun discovers the matching frontend by scanning your examples checkout for an <example>/frontend/package.json directory whose name matches the app's slug.

Listing resources

urun app list       [--json]
urun session list   [--limit 100] [--state STATE] [--json]
urun compute list   [--limit 100] [--json]

• app list — every deployed app with a derived STATUS. See Manage apps.
• session list — live and historical sessions (fetched newest-first, printed newest-last). --state is one of allocated, connected, closed, failed, cancelled. See Sessions.
• compute list — currently-provisioned GPU/instance slices. See Compute.

Many more list targets exist — shape list, capacity list, build list, release list, event list, environment list, capacity-lease list, credit-ledger list, secret list, api-key list, service-account list, member list, activity list, failure-group list, issue list, alert-rule list, alert-channel list, git-installation list — each with common filters (--app, --status, --range, --limit, --environment, …).

urun app

Manage one deployed app, addressed by slug.

urun app status      <app> [--environment ENV] [--json]
urun app scale       <app> --replicas N [--environment ENV] [--json]
urun app concurrency <app> --limit N | --clear [--function NAME] [--environment ENV] [--json]
urun app disable     <app> [--function NAME] [--environment ENV] [--yes] [--json]
urun app enable      <app> [--function NAME] [--environment ENV] [--json]
urun app purge       <app> [--yes] [--json]

• status — build / deployment / capacity / live-session status for one app.
• scale — set desired replica count (--replicas 0 drains without disabling).
• concurrency — max concurrent sessions per function: the platform adds replicas on queued demand up to this limit (default 2) and scales back down when idle. --clear returns control to the app's declared @app.function(max_concurrency=).
• disable — drive the deployment to paused so the control plane stops running it; reversible. With --function NAME, pause just that function: new sessions to it fail fast (409 function_paused), its replicas scale to zero, siblings keep serving; a redeploy clears the pause.
• enable — reverse a disable (drive back to active). With --function NAME, resume a paused function.
• purge — permanently purge orphaned app metadata after a partial deletion (the backend refuses while deployment rows exist).

--environment aliases to --env; default is main. See Manage apps.

Reading resources and account attributes

Read-only inspection of one resource or account-level scalar. <target> is the resource id / slug.

urun account (account attributes)

urun account gpu-metrics    <target> [--function NAME] [--range 1h]
urun account runtime-health <target> [--function NAME]
urun account deploy-status  <target> [--environment ENV]

Other account attributes: org, usage, credit, quota.

urun <resource> get

urun build get         <target> [--json]
urun release get       <target> [--json]
urun shape get         <target> [--json]
urun session get       <target> [--json]
urun capacity get      <target> [--json]
urun environment get   <target> [--json]
urun member get        <target> [--json]
urun issue get         <target> [--json]
urun alert-rule get    <target> [--json]
urun secret get        <target> [--json]   # metadata only, never the value

urun app diagnose, urun session stop

urun app diagnose <app> [--fail-on warn|fail] [--environment ENV] [--json]
urun session stop <session_id> [--reason TEXT] [--yes] [--json]

app diagnose runs health checks against an unhealthy app; --fail-on exits non-zero at the given level (useful in CI). session stop stops one session.

urun log list, urun build logs, urun log tail

urun log list    [--session ID] [--level trace|debug|info|warn|error] [--text QUERY]
                 [--app APP] [--range 1h] [--limit N] [--json]
urun build logs  <build_id> [--tail N] [--json]
urun log tail    [--session ID] [--level LEVEL] [--text QUERY] [--app APP] [--json]

log list is a one-shot log query (full-text via --text); log tail is the live follow with the same filters; build logs prints one build's logs.

urun environment create, urun secret set, urun secret delete, urun app delete, urun use environment

urun environment create <name> [--display-name NAME] [--json]
urun secret set   <name> --value VAL | --from-file PATH [--app APP] [--json]
urun secret delete <name> [--app APP] [--yes] [--json]
urun app delete   <app> [--environment ENV] [--purge] [--yes] [--json]
urun use environment <name>

app delete retires the deployment through the platform lifecycle (reversible with urun app enable until purged); --purge polls until the app record is gone. use environment sets your local default environment.

urun open

urun open billing      [--console-url URL]
urun open git-connect  [--console-url URL]

Open a console page in the browser.

urun config

urun config get default-environment | console-url
urun config set default-environment <name>
urun config set console-url <url>

Local CLI defaults, stored separately from login credentials.

urun feedback

File and track platform feedback to the uRun team.

urun feedback raise "<title>" --body "<markdown>"
                    [--category bug|gap|feature|question] [--app APP] [--session SESSION_ID]
urun feedback comment <feedback_id> "<text>"
urun feedback get     <feedback_id>
urun feedback list

--body is required on raise.

urun dev-gate

Run the dev gate for an app (launches a server-side agent; requires the launch-agents permission).

urun dev-gate <app> [--gpu l4:1] [--first-frame-timeout 120]

urun dashboard, urun view-default

Audited console writes — configure dashboards and saved view defaults.

urun dashboard create        # create / fork a console dashboard
urun dashboard save-config   # save one dashboard config layer (full replace)
urun view-default set        # save a surface's default view config
urun view-default clear      # clear a surface's saved default view

urun org

urun org           # print just the org id (machine-readable)

urun org set-limits

Set or clear org-level spend / capacity limits (audited write).

urun org set-limits [--monthly-usd-cap USD] [--max-concurrent-sessions N]
                    [--max-gpu-units N] [--alert-threshold-pct PCT]
                    [--clear monthly_usd_cap|max_concurrent_sessions|max_gpu_units]

--clear is repeatable to remove individual limits.

urun auth

urun auth trust-jwk <jwks_url> --issuer ISS --audience AUD
                    [--allow-insecure-jwks-url] [--json]

Register a trusted external JWT provider for the org. JWKS URL must be HTTPS unless --allow-insecure-jwks-url. See Trusted JWKS.

urun auth remove-jwk <issuer> [--yes] [--json]

Stop trusting a provider, addressed by its iss claim. --yes / -y skips the confirmation prompt.

Environment variables