Qoren CLI command reference

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.

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.

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#

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.

--size takes a size name or a size slug. Your plan sets the largest size you may use. The four plan slugs, and how region refusals work, are in the Qoren command line.

Resize an environment#

A larger size happens in place: the environment powers off, resizes and comes back up, so its agents are unreachable for a couple of minutes. A smaller size cannot be done in place, so resize builds a new environment at that size, moves every agent to it with everything it has, then removes the old one. The environment keeps its name but gets a new id. Each agent keeps running while its files are copied and pauses only for the final switch-over, and you are billed for one environment throughout. See resize an environment.

Before a shrink starts, the command checks that every agent fits. When the smaller size holds fewer agents than the environment has, or an agent's template needs a larger size, it starts nothing. Instead it lists the agents, your environments with room and the sizes a new environment can have, then prints a command that would work, and exits 1. Say where each extra agent goes with --remove, --move or --overflow, using its id, slug or name. Environments take an id or a name. Warnings, such as a WhatsApp line whose webhook must be pointed at the new environment, go to stderr.

With --json, the refusal goes to stderr as { "error", "detail" }, where detail.plan is the full preview a script can read.

If a shrink's job fails or the platform restarts midway, every agent is either still on the original environment or already on its destination. Run qoren env resize <id> --resume to finish, or --cancel to put everything back. qoren env get shows a shrink that is under way.

qoren env create --name production --size s-2vcpu-2gb-90gb-intel
qoren env assign production "Acme Dental"
qoren env collaboration env_abc123 on
qoren env resize production --size heavy
qoren env resize atlas --size light --move writer=beacon
qoren env resize atlas --size light --remove scout --overflow writer --overflow-size light
qoren env resize atlas --resume

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.

Secret commands#

qoren secrets, also qoren secret and qoren vault. The vault: keys your agents receive by name. Values go in and never come back out, except through reveal, which is logged.

printf '%s' "$ACME_HUBSPOT_KEY" | qoren secrets set HUBSPOT_API_KEY --client Acme

Agent commands#

qoren agent, also qoren agents.

Create, inspect and remove agents#

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#

exec exits 1 when the command it ran exits non-zero. doctor exits 1 when the checkup needs attention or fails.

limits changes only the caps you pass a flag for and keeps the others as they are. Anyone in the organization can see the caps, but only the organization owner can change them; for anyone else a change fails with a 403. Once a cap is reached, the agent's model calls stop until that window resets: at midnight UTC for the daily cap, on Monday for the weekly cap and on the 1st for the monthly cap. The agent resumes within a few minutes of the reset. Caps apply to the agent's own Qoren model key. An agent still waiting for that key gets it within a few minutes, and the caps apply from then. An agent that runs on your own model key is not billed or capped by Qoren. For limits across the whole account, see spend controls.

qoren agent message agt_def456 "Summarize what came in today"
qoren agent exec agt_def456 "ls workspace"
qoren agent doctor agt_def456 --history
qoren agent limits agt_def456 --daily 500 --monthly off

Autonomy#

Each agent has an autonomy policy that decides how much it does on its own. Sources are the kinds of turn: act runs the turn normally, ask runs it as a proposal that waits in qoren approvals. Actions are the kinds of Qoren tool call: allow runs the call right away, ask waits for a person in every turn. Auto-approve set to except-high approves a turn's low and medium risk proposals automatically and leaves high risk ones for a person. Tools that destroy, resize, move or rebuild always ask, whatever the policy says. New agents start on balanced.

The per-row flags read the current policy, change only the rows you name and save the whole policy, so the rest stays as it was. A change applies from the agent's next turn. Anyone in the organization can make an agent more careful, but only an org owner can make it more autonomous: any ask to act or allow, or turning on auto-approve. Anyone else gets "Only an org owner can make this agent more autonomous." and exit code 1. Where the agent's runtime cannot run a kind of turn as a proposal, the in practice column shows act and a note says why. --json prints the policy, what each source does in practice, and the notes.

qoren agent autonomy agt_def456
qoren agent autonomy agt_def456 --preset cautious
qoren agent autonomy agt_def456 --source scheduled=act --action public-links=allow --auto-approve except-high

Chat reactions#

On Telegram, Slack, Discord and Signal an agent reacts to each message it receives with a "working" emoji while it handles it, then swaps it for a "done" emoji once it has replied. You can set both on the account (qoren account reactions), on a client (qoren clients reactions) and on one agent. Each level uses what the level above it sets unless it sets its own, and each slot inherits on its own. With nothing set anywhere, agents use 👀 while working and ✅ when done.

Pass the emoji itself or its name, such as thinking or thumbs-up; the command lists the choices when it does not recognize one. A flag changes only its own slot and keeps the other as it is. Agents pick up a change within seconds, after a brief restart of their messaging gateway. Telegram does not allow every emoji as a reaction: where it does not, agents on Telegram use 👀 while working and 👍 when done instead, and the command says so. Codex and Custom agents do not use chat reactions. Anyone in the organization can see the account's reactions, but only the account owner can change them.

qoren account reactions --working thinking
qoren clients reactions "Harbor Dental" --done 🎉
qoren agent reactions agt_def456 --working inherit --done thumbs-up

Scheduled tasks#

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#

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#

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.

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.

A condition for --when and qoren webhook conditions is a dotted path into the event's body and one test. Values ignore case:

• path=value: the field is that value.
• path=a|b: the field is one of the values.
• path!=a|b: the field is none of the values (a missing field passes).
• path~=text: the field contains the text.
• path:exists or path:missing: the field is present, or absent.

qoren webhook create agt_def456 --name "Failed CI" --source github --event check_suite \
  --when action=completed --when "check_suite.conclusion=failure|timed_out"

Approval commands#

qoren approvals, also qoren approval. What your agents asked to do and are waiting on you for, across every agent: proposals from turns their autonomy policy runs as a proposal, triggers set to Propose only, and tool calls that ask first. Only an org owner can approve or deny. A request the agent's policy approved by itself shows as approved automatically. See approve what your agents ask to do.

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#

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.

Raw API calls#

<method> is GET, POST, PUT, PATCH or DELETE. <path> is relative to the API root, such as agents or machines/abc123.

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#

See the Qoren command line for its keys.