Every qoren command and flag in one place, for environments, agents, scheduled tasks, webhooks, approvals, clients, jobs, account usage and raw API calls.
Every command the qoren CLI has, with its arguments and flags. For installing, signing in, scripting and exit codes, start with the Qoren command line. Run qoren <command> --help for the same information in your terminal.
Arguments in angle brackets are required, arguments in square brackets are optional, and ... means you can repeat it. Wherever a command takes an <id>, use the id that the matching ls command prints.
Global options#
These work with every command.
| Option | Effect |
|---|
--json | Print the result as JSON on stdout; everything else goes to stderr |
--profile <name> | Use this stored login |
--api-url <url> | Talk to a different Qoren server |
--no-color | Turn colour off |
-v, --version | Print the CLI version |
-h, --help | Help for the command you are on |
Exit codes and errors#
Every command exits with one of these codes. The Qoren command line explains how to branch on them in a script.
| Code | Meaning |
|---|
| 0 | Success |
| 1 | The request failed; the message came from the server |
| 2 | The command was typed wrong |
| 3 | Not signed in, or the token is missing, expired or revoked |
| 4 | The plan does not allow this: no active plan, or a plan without API access |
The CLI signs in with an access token, and tokens are API access, which the Ultimate, Business and Enterprise plans include. On any other plan every command, qoren api included, is refused with a 403 whose code is api_access_required. The CLI prints the server's message, which names those plans and links to the pricing page, and exits 4, not 3: the token is fine and signing in again will not help. qoren whoami reports it as REFUSED: your plan does not include API access. In --json mode the structured refusal is on stderr under detail.
Sign-in commands#
| Command | What it does |
|---|
qoren login | Sign this computer in through the browser |
qoren logout | Forget the stored credentials for the current profile |
qoren whoami | Show the profile, server, account, organization and credential in use |
| Flag | On | Effect |
|---|
--token | login | Paste an existing token instead of opening a browser |
--name <name> | login | Name for the token, shown in Settings, CLI tokens. Default cli |
--all | logout | Forget every stored profile |
qoren logout does not revoke the token. Revoke it in the console; see create and revoke access tokens.
Environment commands#
qoren env, also qoren environments.
| Command | What it does |
|---|
qoren env ls | List your environments (also list) |
qoren env get <id> | Show one environment: size, region, image, IP, collaboration, client and hourly cost |
qoren env create --name <name> | Create an environment and follow the job |
qoren env assign <environment> <client> | Put an environment under a client (id or exact name), or pass none to take it off |
qoren env rm <id> | Destroy an environment and every agent on it (also destroy) |
qoren env rename <id> <name> | Rename an environment |
qoren env resize <id> --size <size> | Move an environment to a larger size; it restarts while this runs |
qoren env vitals <id> | Print live host readings (CPU, memory, disk) as JSON |
qoren env collaboration <id> <state> | Turn agent to agent messaging on the environment on or off |
| Flag | On | Effect |
|---|
--name <name> | create | Required. The environment's name |
--size <size> | create, resize | The size slug from qoren account options. Required on resize |
--region <region> | create | Pin a region, for example fra1. Omit to let the platform choose |
--auto-region | create | If the pinned region cannot run the size, use the closest region that can |
--image <image> | create | Base image. Omit for the default |
--org <slug> | create | Organization slug. Found automatically, so you rarely need it |
--client <client> | create | Assign the new environment to a client (id or exact name) |
--no-wait | create, rm, resize | Print the job id and exit instead of following the job |
Always pass --size with a size slug on create. The --help text shows light | standard | heavy | max with a default of light, but those names are refused: without --size, or with a name, the create fails with "That environment size isn't available on your plan." and exits 1. The four plan slugs, and how region refusals work, are in the Qoren command line.
qoren env create --name production --size s-2vcpu-2gb-90gb-intel
qoren env assign production "Acme Dental"
qoren env collaboration env_abc123 on
Client commands#
qoren clients, also qoren client. These work only on accounts with clients turned on; otherwise they answer "Clients are not enabled for this account." See clients.
| Command | What it does |
|---|
qoren clients list | List your clients (also ls) |
qoren clients create <name> | Add a client |
qoren clients rename <client> <name> | Rename a client, by id or current name |
qoren clients archive <client> | Archive a client; its environments must be unassigned first, and its cost history is kept |
| Flag | On | Effect |
|---|
--archived | list | Include archived clients |
--email <email> | create | Contact email |
--notes <notes> | create | Free-form notes |
Agent commands#
qoren agent, also qoren agents.
Create, inspect and remove agents#
| Command | What it does |
|---|
qoren agent ls | List your agents (also list) |
qoren agent get <id> | Show one agent: runtime, model, template, environment, secret names and chat channels |
qoren agent create --env <id> --template <slug> --name <name> | Deploy a new agent onto an environment and follow the job |
qoren agent rm <id> | Remove an agent; a final snapshot is taken first so it can be restored (also destroy) |
qoren agent rename <id> <name> | Change the display name |
qoren agent import <bundle> | Deploy an agent from an export of a self-hosted Hermes, OpenClaw or Codex install |
| Flag | On | Effect |
|---|
--env <id> | ls | Only agents on this environment |
--env <id> | create, import | The environment to deploy onto. Required on create, and on import unless --dry-run |
--template <slug> | create | Required. The template to build from (see qoren account templates) |
--name <name> | create, import | Display name. Required on create; import defaults to the bundle's file name |
--slug <slug> | create, import | The agent's permanent identity. Defaults to one made from the name |
--model <model> | create, import | Model id. Defaults to your account default (import first tries the model the export used) |
--runtime <runtime> | create | hermes, openclaw or codex. Default hermes |
--secret <name...> | create | A vault secret to give the agent, by name. Repeatable |
--template <name> | import | Name for the template the import saves. Defaults to the agent name |
--import-secrets | import | Store the secret values carried by an export made with secrets in the vault, and attach them |
--dry-run | import | Show what would be sent and stop before any API call |
--no-wait | create, rm, import | Print the job id and exit |
Only secret names travel with --secret; the values are filled in on the server from your vault. If the pre-deploy safety review finds a serious problem, create fails and prints each finding with a suggested fix. The export comes from running curl -fsSL https://qoren.sh/migrate.sh | sh on your own server; see migrate an agent to Qoren.
Work with a running agent#
| Command | What it does |
|---|
qoren agent message <id> <message> | Send the agent a message and print its reply |
qoren agent exec <id> <command> | Run a shell command as the agent's own user and pass its output through |
qoren agent logs <id> | Print the agent's recent log |
qoren agent status <id> | Probe the agent now and list its recent failures |
qoren agent doctor <id> | Run the runtime's own doctor and let it repair what it finds |
qoren agent telemetry <id> | Print the agent's model spend as JSON |
qoren agent usage <id> | Show credits the agent spent and its sessions, on the managed key or your own |
| Flag | On | Effect |
|---|
--resume <sessionId> | message | Continue a previous conversation instead of starting a new one |
--no-wait | message | Print the job id and exit instead of waiting for the reply |
--limit <n> | logs | How many lines. Default 200 |
--no-repair | doctor | Report only, without letting the runtime repair itself |
--no-wait | doctor | Return as soon as the checkup is underway |
--history | doctor | List recent checkups instead of running one |
--limit <n> | doctor | How many checkups to list with --history. Default 10 |
--days <n> | telemetry | Window in days |
--days <n> | usage | Window in days, 1 to 90. Default 30 |
exec exits 1 when the command it ran exits non-zero. doctor exits 1 when the checkup needs attention or fails.
qoren agent message agt_def456 "Summarize what came in today"
qoren agent exec agt_def456 "ls workspace"
qoren agent doctor agt_def456 --history
Scheduled tasks#
| Command | What it does |
|---|
qoren agent tasks <id> | List the agent's scheduled tasks and how healthy each one is |
qoren agent task-runs <id> <task-id> | Show a task's recent runs and where each result was delivered |
qoren agent task-add <id> <name> <cron> <prompt> | Create a scheduled task |
qoren agent task-set <id> <task-id> <name> <cron> <prompt> | Replace a scheduled task |
qoren agent task-rm <id> <task-id> | Delete a scheduled task |
| Flag | On | Effect |
|---|
--limit <count> | task-runs | Number of runs, 1 to 100. Default 25 |
--timezone <zone> | task-add, task-set | IANA timezone. Default UTC on task-add; unchanged on task-set when omitted |
--delivery <policy> | task-add, task-set | activity-only, all-channels (every chat channel, Hermes only), or chat (needs --deliver-to) |
--deliver-to <target> | task-add, task-set | Send each result to one chat, for example telegram:-1001234567890 or slack:C0123ABC. Implies --delivery chat |
--context-from <task> | task-add, task-set | Read the latest output of another task of this agent first: a task id, a task name, or self. Repeat for up to 5 |
--no-context-from | task-set | Stop reading other tasks' output |
--disable | task-set | Keep the task without running it |
--enable | task-set | Resume a disabled task |
A chat target is PLATFORM, PLATFORM:CHAT_ID or PLATFORM:CHAT_ID:THREAD_ID, and the platform must be one of the agent's connected chat channels. See scheduled tasks.
qoren agent task-add agt_def456 "Morning brief" "0 8 * * 1-5" "Summarize my inbox" \
--timezone Europe/Amsterdam --deliver-to telegram:-1001234567890
Keys and ChatGPT sign-in#
| Command | What it does |
|---|
qoren agent keys <id> | List the keys the agent carries, by name and source. Values are never shown |
qoren agent chatgpt-login <id> | Sign a Codex agent into your ChatGPT account with a one-time code |
qoren agent chatgpt-logout <id> | Put the agent back on the platform model key |
| Flag | On | Effect |
|---|
--revoke <name...> | keys | Take these keys off the agent. Only keys you set can be revoked |
--no-wait | keys, chatgpt-login | Print the job id and exit |
chatgpt-login prints a web address and a code, then waits while you approve it in a browser. See sign in to ChatGPT for Codex.
Public file links#
| Command | What it does |
|---|
qoren agent share <id> <path> | Publish one workspace file as an expiring public link and print the link |
qoren agent links <id> | List the links this agent has published, with status, expiry and how often each was opened |
qoren agent unshare <id> <linkId> | Switch off a link so it stops working for everyone |
| Flag | On | Effect |
|---|
--expires <duration> | share | How long the link works, such as 30m, 2h or 3d. Default 7d |
--label <text> | share | A short note to tell links apart |
--max-downloads <n> | share | Stop serving after this many opens or downloads |
Only files under the agent's workspace/ folder can be shared, up to 4 MB each, for at least a minute and at most 30 days. The link is printed once and cannot be read back later.
Webhook commands#
qoren webhook, also qoren webhooks or qoren trigger. A trigger gives an agent a URL that another service can call to wake it. See webhooks for how triggers behave.
| Command | What it does |
|---|
qoren webhook sources | List the services Qoren can receive webhooks from |
qoren webhook ls <agentId> | List an agent's triggers (also list) |
qoren webhook get <id> | Show one trigger |
qoren webhook create <agentId> --name <name> | Create a trigger and print its URL and secret, once |
qoren webhook rules <id> <text> | Rewrite what the agent should do when the trigger fires |
qoren webhook events <id> [names...] | Set which events it acts on; no names means every event |
qoren webhook pause <id> | Stop deliveries without changing the URL |
qoren webhook resume <id> | Accept deliveries again |
qoren webhook rotate <id> | Issue a new URL and secret; the old URL stops working |
qoren webhook test <id> | Send a sample event through the real path |
qoren webhook deliveries <id> | What the trigger received, newest first (also log) |
qoren webhook delivery <id> <deliveryId> | One delivery: its payload and the agent's reply |
qoren webhook replay <id> <deliveryId> | Run a past delivery through the agent again |
qoren webhook rm <id> | Delete a trigger and its delivery log (also delete) |
| Flag | On | Effect |
|---|
--name <name> | create | Required. What this trigger is for |
--source <source> | create | cal, github, stripe, generic or none. Default cal |
--event <name...> | create | Only act on these events. Repeatable; omit for every event |
--rules <text> | create | What the agent should do when this fires |
--propose | create | Let the agent only propose actions, not take them |
--max-per-hour <n> | create | Paid agent turns per hour before deliveries are throttled |
--secret <secret> | create | The signing secret the sender already has |
--header <name> | create | generic source: the header carrying the signature |
--encoding <encoding> | create | generic source: hex or base64 |
--prefix <prefix> | create | generic source: the signature prefix, such as sha256= |
--event-path <path> | create | generic and none sources: where the event name sits in the body, such as type |
--event <name> | test | The event name to simulate |
--limit <n> | deliveries | How many to show. Default 20 |
qoren webhook create agt_def456 --name "Bookings" --source cal \
--event BOOKING_CREATED --rules "Add the attendee to the CRM and brief me."
Every delivery that reaches the agent is a paid turn, so name the events you care about with --event.
Approval commands#
qoren approvals, also qoren approval. What your agents asked to do and are waiting on you for, across every agent: proposals from agents in approval mode, triggers set to Propose only, and platform tools that ask first. See approve what your agents ask to do.
| Command | What it does |
|---|
qoren approvals ls | Requests waiting for a decision, newest first (also list; plain qoren approvals runs it) |
qoren approvals approve <id...> | Approve one or more requests; approved actions go ahead |
qoren approvals deny <id...> | Deny one or more requests; nothing runs |
| Flag | On | Effect |
|---|
--decided | ls | Show approved, denied and expired requests instead |
--all | ls | Show waiting and decided requests together |
--limit <n> | ls | How many to show, 1 to 200. Default 50 |
--note <text> | deny | Tell the agent why, and what to do instead |
qoren approvals
qoren approvals deny apr_123 --note "Send it to the shared inbox instead."
Requests an agent proposed in one turn are best decided in one command, so the agent resumes once with every decision: qoren approvals approve apr_123 apr_124.
Account commands#
| Command | What it does |
|---|
qoren account usage | Credits used and left, balance, model spend and web operations this billing period, with a warning when agents are stopped |
qoren account spending | Model spend per environment over a window |
qoren account costs | What each client cost over a window, in credits and dollars |
qoren account options | The sizes, regions and models you can choose from, with the defaults marked |
qoren account templates | The templates you can deploy agents from |
| Flag | On | Effect |
|---|
--days <n> | spending | Window in days. Default 30 |
--from <date> | costs | Start of the window, an ISO date. Default 30 days before --to |
--to <date> | costs | End of the window, an ISO date. A bare date includes that whole day. Default now |
qoren account usage warns separately when you are out of credits (fixed by topping up) and when your monthly budget has been reached (fixed by raising or clearing the budget). See spend controls.
Job commands#
qoren jobs, also qoren job.
| Command | What it does |
|---|
qoren jobs ls | List recent jobs with their status and steps done (also list) |
qoren jobs get <id> | Show one job, its steps and its error if it failed |
qoren jobs watch <id> | Follow a running job until it finishes |
qoren jobs cancel <id> | Ask a running job to stop; a step already running finishes first |
| Flag | On | Effect |
|---|
--limit <n> | ls | How many jobs. Default 20 |
Raw API calls#
| Command | What it does |
|---|
qoren api <method> <path> | Call any endpoint directly and print the raw JSON answer |
<method> is GET, POST, PUT, PATCH or DELETE. <path> is relative to the API root, such as agents or machines/abc123.
| Flag | Effect |
|---|
--data <json> | Request body as JSON, @filename to read a file, or @- to read stdin |
--query <key=value...> | Query string parameters. Repeatable |
Operator-only endpoints answer 403 to every customer account, from here as from anywhere else. A plan without API access answers 403 with the code api_access_required to every path; see exit codes and errors.
Interactive mode#
| Command | What it does |
|---|
qoren tui | Open interactive mode (also qoren ui, or qoren with nothing after it at a terminal) |
See the Qoren command line for its keys.
