CLI

The beeuni command line, its auth model, the dev loop, and every command.

The beeuni command line interface (CLI) controls Beeuni from a terminal — your laptop or a session sandbox. This page shows the everyday dev loop, then lists every stable command and flag.

Install

curl -fsSL https://beeuni.ai/install | bash

The installer downloads a prebuilt binary for macOS and Linux. Windows is not supported.

Auth model

Beeuni stores authentication per host, not globally. A host is one Beeuni API endpoint. Use cloud to connect to Beeuni.

The config file lives at ~/.config/beeuni/config.json, mode 0600. Override its path with BEEUNI_CONFIG_FILE.

The CLI follows one hierarchy: host → account → project → session. You sign in to a host, pick an account inside it, pick a project inside that account, and open sessions inside the project. beeuni hosts login walks the first three steps in order: it signs you in, picks the account, then sets a default project.

Every token starts with beeuni_pat_. A user token, from beeuni login, sees every account and project you belong to. A project token is auto-minted for a session sandbox and scoped to one project. See Token scope.

The dev loop

This loop assumes the CLI is installed and you ran beeuni login. See Quickstart for setup.

beeuni init my-app
cd my-app

beeuni projects link <project-id>

beeuni ship

beeuni sessions new --prompt "Build the login page" --wait

beeuni connect

beeuni sessions chat

beeuni tui        # or: beeuni t, or beeunit
beeunit --project <id> --new --terminal   # new session + sandbox shell, one command

beeuni sessions shell

beeuni sessions ls

beeuni cr ls
beeuni cr diff 1
beeuni cr merge 1

Reference

Auth commands

beeuni hosts login / hosts logout / hosts whoami are the canonical forms. login / logout / whoami are shortcuts that act on the active host.

Hosts

A remote host URL that starts with http:// is normalized to https://. The CLI never sends a token over plain HTTP to a remote host. localhost is exempt.

Accounts

Members

Who belongs to the account, and at what account role. Roles are owner, admin, and member. Owners and admins hold implicit Manager on every project, so member is the only role that takes per-project grants.

A <user> is a user id, or the email of someone already in the account. Options: --account <id>, --host <name>, --json, -y.

Groups

An account group is a named set of people you grant a role to once. Bind a group to a scope with beeuni access grant --group <id> --role <key>; revoke with beeuni access revoke <assignment-id>.

A <group> is a group id or its exact name. Reads need group.read. create, set, and add need group.update or group.members.manage, plus the enterprise rbac entitlement. rm and remove are cleanup and are never entitlement-gated.

Tokens

Non-interactive credentials for the account. Reads need token.read. Every account member may mint and revoke their own personal keys (token.personal.create, token.personal.revoke); a personal key acts as you and never carries more than your own roles. Service accounts and other people’s keys need token.create / token.revoke (owner and admin).

A personal API key acts as you and dies with your membership. A service account acts as itself and inherits no access: a new one holds no permissions. Grant it one with beeuni access grant --service-account <id> --role <key>. --expires <when> takes ISO-8601 or a forward span: 30d, 12h, 6w, 1y.

Billing

Read the active account’s plan, credits, and spend. Read-only: plan changes, top-ups, and payment methods are dashboard flows.

Filters: --project <id>, --session <id>, and --owner <id> (sessions, with --by session). Options: --account <id>, --host <name>, --json.

Projects

A command resolves “the project” in this order:

1. The --project flag.
2. The BEEUNI_PROJECT_ID environment variable.
3. .beeuni/link.json in the exact working directory.
4. The global default set by beeuni projects use.

A project shows one icon, so writing --icon clears the glyph and writing --glyph clears the emoji; passing both is refused. Glyph colors: grey, red, orange, yellow, lime, blue, purple, magenta. set and features need project.settings.write. A flag the platform marks unavailable stays off regardless of the project override.

A project CLI token is bound to one project — the API rejects it everywhere else. A session sandbox uses its session-bound BEEUNI_TOKEN. cli-tokens ls needs project read; new and rm need project.credentials.issue. A session-bound token can neither mint nor revoke project tokens (403), whether or not the project declares agents. A project CLI token follows the account’s PAT policy: when the account requires an expiry, pass --expires-at; an expiry beyond the maximum lifetime returns 400.

beeuni projects upgrade needs project write. The default agent refreshes the marketplace baseline, rewrites the manifest, runs beeuni validate, and opens a change request. It never merges: a human reviews the diff.

Project scaffold

beeuni init [project-name] [options] creates a new project directory. The starter writes a v2 beeuni.yaml, agents/, skills/, memory/, and harnesses/opencode/. The command can wire local coding-tool discovery without changing the default agent runtime. The command does not write .beeuni/link.json. beeuni ship or beeuni projects link create that file.

The local coding-tool selection does not change the default agent runtime.

beeuni init does not include a marketplace picker. Adding a marketplace skill is an agent import: start a session and ask the agent to bring one in.

Ship

beeuni ship stages, commits, and pushes your current branch to the project’s git repo. Run it once to create the project. Run it again any time to sync. Alias: beeuni deploy.

Each run:

• Runs the beeuni validate checks: beeuni.yaml merged with every file it lists under imports:, sandbox Dockerfiles, agent wiring, and repository size (skip with --no-verify). An error stops the ship. A warning never does.
• Commits any dirty working tree (skip with --no-commit).
• Prompts for any missing env secret (skip with --no-env).
• Pushes the current branch to the same-named remote branch.
• Connects any declared connector that still needs auth (skip with --no-connect).

An existing GitHub origin links through the Beeuni GitHub App. Any other existing origin is registered as-is. No origin creates a managed Beeuni git repo.

Apps

Apps host static sites, servers, workers and databases. Each App has a stable URL. A release contains its code and configuration; a failed deployment does not replace the active release.

beeuni apps list
beeuni apps show main
beeuni apps connect main
beeuni apps launch --template convex --slug main
beeuni apps deploy dist --type static --spa
beeuni apps machines main
beeuni apps volumes main

Connect applications with uses and use the connection examples shown by beeuni apps connect. Keep administrative credentials out of client-side code.

Running resources consume account credits. Check Billing and Usage for your balance. Apps do not have a separate monthly budget.

Apps

Sessions

Each session runs in one sandbox on its own branch.

sessions queue needs project.session.start — the same permission as sending a message. A queued prompt survives a closed terminal and is delivered when the session can take it. Put one there with beeuni sessions chat <id> -p "…" --queue, or steer the running turn with --steer. sessions queue ls shows each prompt’s DELIVERY (steer, queue or interrupt) and, for a steer prompt that runs as queue, the reason: unsupported (the session cannot take messages mid-turn), not_prompter (another member’s turn is running) or turn_ended.

sessions approvals are durable: unlike sessions pending, they survive a sandbox restart. It needs project.members.manage, or being the human who launched the session. An agent may never resolve its own approval.

sessions attachments reads the session’s private file store, not its workspace. Files land there at send time, and every file the agent showed lands there at the end of the turn.

sessions files reads the working tree the agent is editing right now, before anything is committed; beeuni files reads the committed repo instead. Paths resolve under /workspace unless they start with /workspace, /tmp, /home, or /opt. The command wakes the sandbox if it is asleep. Options: --from <local path> (write reads this file instead of stdin), --content (find greps contents with ripgrep instead of filenames), --limit <N> (find filename cap), and -y to skip the rm confirmation.

sessions share is owner-governed: the API refuses a project manager who cannot already read the session. A shared session runs only on provider keys shared with the whole project: a model that ran on your own keys switches to the project’s keys for that provider, and with none that runs it, the share is refused (409 SHARED_SESSION_NEEDS_PROJECT_KEY).

sessions links create options: --port <n> (default 3000; 22, 8000, and the opencode ports are refused), --path <p> (default /), --preview <id> (a named candidate — web, vite, dev-server, api-docs — instead of --port/--path), --file <path> (share one workspace file instead of a preview; always read-only), --mode view\|interactive (default view; interactive allows writes and websockets, and is ignored for --file), --label <text>, and --expires <iso>. Minting a link needs the session owner, because the link itself needs no login; listing and revoking also accept a project manager.

Inside a sandbox, BEEUNI_SESSION_ID is your own session’s id.

Change requests

A change request (CR) merges one branch into another on any git host. It is the only way for an agent to land session work on the default branch. See Change requests.

request-changes records the note on the CR and delivers it to the originating session, booting its sandbox if it is asleep. It needs project.review.act — the same leaf the Review Center uses, not gitops.push.

<cr> accepts a per-project number (3) or the full id. Inside a sandbox, the CLI reads its token automatically — no login or link needed.

Review

The project’s review inbox — everything waiting on a human decision: change requests, connector tool calls a policy gated for approval, and the outputs, decisions, and batches agents submit for sign-off. Mirrors the dashboard’s Review Center. On for every project; project.review.read and project.review.act gate reading and acting.

Verdicts: approve, reject, changes, answer, dismiss. Segments: needs_you, waiting, done. Kinds: change, approval, output, decision, batch.

Where a verdict lands depends on the item id. On cr:<id>, approve merges the change, reject closes it, and changes sends the note back to the agent that opened it (--message required). On call:<id>, approve lets the tool call run and reject denies it; a connector approval takes no other verdict — read its arguments first with beeuni review show. Every other id goes to the native act endpoint, which takes every verdict.

bulk acts on native ids only. A connector approval needs its own parameter review and a change request needs its diff in view, so both are reported and skipped — the same rule as the dashboard’s multi-select.

submit options: --kind output\|decision\|batch (required), --title <text> (required), --summary <text>, --risk none\|low\|medium\|high (default none), --detail <json> (a JSON object), --agent <name>, and --session <id> (ignored when it is not this project’s session).

Reads need project.review.read, verdicts need project.review.act, and submit needs project.review.submit.

Secrets

Encrypted values stored on the project. By default a secret injects as a plain environment variable into every session sandbox at boot (environment exposure). Enforced delivery — where the sandbox holds a handle and Beeuni substitutes the real value outside it (egress-enforced exposure, and beeuni secrets call) — is experimental. Enable the secrets_egress feature flag (Settings → Feature flags) to use it; with the flag off, beeuni secrets delivery … egress returns 403 feature_disabled. See Secrets.

grant is the fix for a row ls reports as undeliverable. It only ever widens one agent’s list; to narrow or replace it, rewrite the whole set with beeuni agents scope. There is no secrets revoke — the API has no route that removes a single identifier from a grant. The first grant on a project with no agents starts governance: from then on, an agent the manifest does not list receives no project secrets, and the command says so when it happens.

Env

Agents

Per-agent model settings on the linked project.

Every scope option replaces; none merge. A --set value is parsed as JSON when it parses, and kept as a string otherwise. Model pins and scope apply instantly, with no beeuni.yaml commit; default and config commit to beeuni.yaml on the project’s default branch. scope needs project.agent.write, and so do default and config.

Tools

The tools this project’s sessions get, read from the local beeuni.yaml and its imports. Run from the project root. See Tools.

With no tools: key, every session gets all five Beeuni tools (web_search, image_search, scrape_webpage, memory, show). With a tools: key, sessions get only the Beeuni tools it lists. To remove a Beeuni tool, delete its line under tools:, then run beeuni validate. To limit the tools of one agent, use agents.<name>.tools. Exit codes: 0 done, 1 refused (a file exists, a manifest or import that does not parse), 2 no manifest, an unknown option, or a name that is not a Beeuni tool.

Models

Which models the project offers, and which one it starts with. Same surface as the dashboard’s Customize → Models. A project stores only its exceptions to the catalog default (the newest model of each family). Enablement is display-only: it decides what pickers offer, never what the gateway serves.

Model ids are gateway wire ids — a bare managed id (glm-5.3-flash) or a BYOK provider/model. Copy one from beeuni models ls --json. Per-agent pins live on beeuni agents model <agent> <model-id>. Writes need project.model.write.

Channels

Manages the project’s connection to a chat platform. Tokens are stored encrypted in the project’s secrets and resolved server-side — they are never injected into the sandbox.

--platform slack|teams selects the platform; default slack. Teams connect prints the Microsoft admin-consent URL; granting tenant-wide consent publishes the app to your Teams catalog automatically. See Connectors.

The email channel is AgentMail-backed and needs the agentmail_email feature flag. email connect options: --connector <slug> (default beeuni_email), --api-key <k> (bring your own AgentMail key; - reads stdin), --display-name <n> (from-name on outgoing mail; default the project name), --username <u> and --domain <d> (a new managed inbox), and --inbox-id <id> with --email <addr> (attach an existing inbox — both are required together). --allow is repeatable and puts the policy in restricted mode; a bare value with no @, or one with a leading @, is read as a domain. --allow-all clears the list and accepts every sender again.

Email and bind writes need project.connector.write.

Connectors

Connectors an agent calls as tools. add, rm, and policy set edit the local beeuni.yaml; run beeuni ship to apply, unless you pass --apply to change the cloud project immediately.

policy ls, show, set, add, and rm are the project-wide surface, so a connector named after one of those verbs must be addressed as policy <slug> ls. A <match> is a tool name, a glob (send_*), or a /regex/.

add options: --name <label>, --provider <pipedream\|mcp\|openapi\|postman\|graphql\|http>, --app <slug>, --url <url>, --transport <http\|sse>, --endpoint <url>, --base-url <url>, --spec <url\|path>, --auth-type <none\|bearer\|basic\|custom>, --credential shared.

Sandboxes

Manages the project’s sandbox images. A template defines an image or Dockerfile plus resources; a build produces the snapshot sessions boot from.

Pinning a provider needs project.settings.write.

add/update options: --name <label>, --cpu <n>, --memory <n> (GiB), --disk <n> (GiB).

Backends

Databases are Apps with persistent volumes. Manage and connect them through Apps.

Apps

Marketplace

Browse the Beeuni marketplace, and install an item into a project.

Options: --query <text>, --type <type>, --source <source>, --host <name>, --project <id>, --json.

Install is agent-driven: it starts a project session that clones the item, reads it, merges what fits, and opens a change request. There is no deterministic install/update/remove machinery.

System skills

The Beeuni system skills are the platform’s operational reference for both people and agents. They cover sessions, sandboxes, default runtime, connectors, memory, and channels. This public page is the entry point; the authenticated CLI reads the skills from the running host. Use beeuni system-skills list to discover the available skills, then get the one you need. The API serves them live, so they match the deployed host version. Do not treat a local copy as current.

Options: --host <name>, --json.

beeuni skills is a permanent alias for the same command. Sign in to the host first with beeuni login; the skills API requires authentication. Use --host <name> when working with another host. A public docs page cannot replace these live, host-specific instructions.

This list is always the system skills, never a mix. Optional skills live in the marketplace: beeuni marketplace list --type skill. For command syntax, use beeuni <command> --help; for the complete platform reference, read beeuni system-skills get beeuni-system --full.

Connector

The in-sandbox agent’s interface to every connector. Every call is checked, resolved, and audited server-side; the CLI never holds a third-party credential. Auth: BEEUNI_TOKEN. Output is JSON.

Files

Read-only view of the project’s git repo. Operates on the default branch unless --ref names another branch, tag, or commit.

Options on every subcommand: --ref <ref>, --path <p>, --limit <n>, --json. download also takes -o, --out <file>, which is required.

Every subcommand needs project.file.read. download additionally refuses any subtree that would include an agent or skill you are scoped out of — a zip cannot be filtered mid-stream — so archive a narrower --path in that case.

Triggers

A trigger starts a session from a schedule, a webhook, an app event, or a monitor (experimental). add, rm, enable, disable edit the local manifest — run beeuni ship to apply. pause/resume flip a separate, server-side switch. See Triggers.

add options: --type <cron\|webhook\|event\|monitor> (default cron), --prompt <text> (required), --agent <name>, --cron <expr> (6-field, e.g. "0 0 9 * * 1-5"), --run-at <iso> (run once at this instant instead of on a cron), --timezone <tz> (default UTC), --secret-env <NAME>, --name <label>, --disabled.

Live-only options — valid on add --apply, and on every set: --model <provider/model>, --session-mode <fresh\|keyed\|pinned\|reuse>, --session-key <tmpl> (bucket one session per key, e.g. "{{ body.data.chat_jid }}"; implies keyed), --session-id <id> (the session a pinned trigger loops; must be this project’s session), --session-access <private\|project\|members> (default private), --member <uuid> and --group <uuid> (repeatable; each implies members), and --filter <path=value> (repeatable; every one must match, e.g. --filter body.type=push).

set takes every live-only option plus --name, --prompt, --cron, --run-at, --timezone, --secret-env, --agent, and --enabled true|false. --cron and --run-at are exclusive: setting one clears the other. Monitor fields are add-only.

Reminders

A reminder re-prompts one session later, once or on repeat. It is stored in the database, not beeuni.yaml. Inside a session, --session defaults to $BEEUNI_SESSION_ID. See Reminders.

Schedule options: --in <duration> or --at <iso> (first fire; alone, fire once), --every <duration> (repeat, min 5m), --cron "<expr>" with --timezone <tz>. Other options: --name <label>, --session <id> (a unique prefix works), --project <id>, --host <name>, --json.

Event options (--type event): --connector <slug> and --event <TYPE> (both required), --config key=value (repeatable, string values), and --config-json '{...}' (typed values). set accepts the same flags. An event trigger rejects --cron, --run-at, --timezone, --secret-env, and the monitor options. The prompt reads {{ event.data.<field> }}; see App event triggers.

Monitor options (--type monitor): --run <cmd> (repo-relative command to supervise; required), --mode <poll\|stream> (required; poll re-runs on --interval, stream keeps the command alive), --interval <dur> (mode=poll only, minimum 30s, e.g. 60s, 5m), and --expect-event-within <dur> (silence watchdog; no event inside the window fires a lifecycle event instead, minimum 5m, e.g. 24h). A monitor is a repo command the platform runs 24/7, and each stdout line fires the trigger. It is experimental: the platform runs monitors only where the monitors feature flag is on.

Access

The CLI face of the one grant table. Every row is an assignment: one principal, one role, one scope, optionally narrowed to one object. See Accounts & access for the model. Account roles: owner, admin, member. Project roles: manager, member.

Grant options: --project <id> (default: the linked project), --account (the whole account), --agent <name> (narrow the grant to one agent — an object assignment), --connection <id> (narrow the use of one shared connector account; the first grant limits the account to its grantees, and revoking the last opens it to the whole project again), --everyone (grant to everyone with access to the project; it holds an --agent or a --connection, never a role), and --expires <iso> (auto-revoke timestamp). --principal filters a list, and takes user:<id>, group:<id>, service_account:<id>, project:<id>, or pending:<email>; a bare id is read as a user. A grant to everyone lists as everyone. An agent’s identity is a service_account, so --service-account <id> is how you assign a role to an agent. --user accepts an email and resolves it against the account member directory.

beeuni access grant --user alice@corp.com --role manager
beeuni access grant --user alice@corp.com --role admin --account
beeuni access grant --group 8f3c… --role member --project 1a2b…
beeuni access grant --user alice@corp.com --agent support-bot
beeuni access grant --everyone --agent support-bot
beeuni access grant --group 8f3c… --connection 2b7e…
beeuni access revoke 4d5e…

The project member verbs are a read model over the same assignments:

Every verb in the two blocks above needs project.members.manage.

A person, a group, or an agent gets roles from Beeuni; an agent additionally carries Beeuni permissions in beeuni.yaml, and a session can only do what both allow. See One vocabulary, two bindings.

Audit

The audit commands read the centralized reconstruction log. Account and project lists are newest first. A session timeline is ordered by creation time (session_sequence is set only on rows written before 2026-10, which come first). --all follows every continuation cursor. ls lists the last 90 days; export reaches back 365 days, and events older than 90 days come from the archive (see Audit retention). The table shows each row’s title (EVENT, for example “Revoked LLM gateway key”) next to its ACTION (gateway.key.revoke); --action filters by action prefix. Every action and title: Audit log actions.

Audit webhooks stream the trail to a SIEM. Every verb needs account.write; add and enable also need the enterprise entitlement. disable and rm never do.

Filters: --actor, --actor-type, --project, --session, --source, --phase, --outcome, --action, --resource-type, --request-id, --correlation-id, --query, --since, --until, --cursor, and --limit. Account lists and exports require audit.read and the account’s auditAccess entitlement. Project-wide lists require project.members.manage because they can include private-session metadata. Session reconstruction requires project.session.read and visibility of that session.

Roles

A role is a named set of permissions. System roles (owner, admin, member at account scope; manager, member at project scope; plus agent-user, the marker an object assignment carries) are read-only references. Custom roles are yours to create and edit, and need the enterprise rbac entitlement.

Bind a role to a principal with beeuni access grant. The older beeuni roles assign / unassign / assignments verbs still work and write the same table, but beeuni access is the documented path. beeuni roles actions is superseded by beeuni permissions ls.

A custom role only adds permissions. Beeuni has no deny rule, so a role cannot withhold a permission from a manager.

Permissions

The permission catalog, as data. One row per leaf action, with the scope it is decided at, whether it is delegable, and what it implies. Roles are built from these keys — beeuni roles create --actions and beeuni roles set-actions take exactly them. Alias: beeuni perms.

Grants

Assigns one project object to a principal — an object assignment. Secrets and connectors live on agents, so assigning an agent to a person grants everything that agent declares. An agent is closed by default: a member reaches it only when an assignment names them or one of their groups. beeuni access grant --agent <name> writes the same row.

Manifest validation

See Manifest reference.

Repository size

A session builds its agent config from every file Git tracks at the base commit. A new session takes those files from its own checkout, whatever the size. A running session picks up a base-branch change through the project snapshot, which Beeuni cloud builds up to 512 MiB compressed; above that, the session keeps the config it runs until a new session starts. Every session also downloads every file. beeuni validate counts the files Git stores, plus the untracked files beeuni ship commits next, and prints a warning when one file is 10 MiB or more or the total is over 512 MiB. A Git LFS file counts as its pointer, because the release holds only the pointer. The warning names the largest files. It never fails the command.

To clear it:

• Move big static assets (video, images, datasets, model weights) to object storage such as S3, R2, or GCS, or a CDN, and download them at runtime.
• Add build output (dist/, out/) to .gitignore.
• For a path that must stay in Git but that no agent reads, add <path> export-ignore to .gitattributes. The release leaves it out, and so does the check; a directory rule covers everything under it. The agent config dir and beeuni.yaml always ship whole.

Token scope

Every token starts with beeuni_pat_. A user token is scoped to every project on your accounts. A project token is scoped to one project and auto-injected into that project’s sandboxes. See the full token-family reference at Session runtime.

Exit codes