CLI

The singulacomp command line interface (CLI) controls SingulaComp 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://singulacomp.ai/install | bash

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

Auth model

SingulaComp stores authentication per host, not globally. A host is one SingulaComp API endpoint. Four hosts exist by default: cloud (SingulaComp Cloud), selfhost (your self-hosted stack), local-dev, and singulacomp-internal-dev. You can add more.

The config file lives at ~/.config/singulacomp/config.json, mode 0600. Override its path with SINGULACOMP_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. singulacomp 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 singulacomp_pat_. A user token, from singulacomp 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 singulacomp login. See Quickstart for setup.

singulacomp init my-app
cd my-app

singulacomp projects link <project-id>

singulacomp ship

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

singulacomp connect

singulacomp sessions chat

singulacomp sessions shell

singulacomp sessions ls

singulacomp cr ls
singulacomp cr diff 1
singulacomp cr merge 1

Reference

Auth commands

singulacomp 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 singulacomp access grant --group <id> --role <key>; revoke with singulacomp 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, minting needs token.create, revoking needs token.revoke.

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 singulacomp 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 SINGULACOMP_PROJECT_ID environment variable.
3. .singulacomp/link.json in the exact working directory.
4. The global default set by singulacomp 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.customize.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 SINGULACOMP_TOKEN. cli-tokens ls needs project read; new and rm need project.credentials.issue. An agent-session token can neither mint nor revoke project tokens (403).

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

Project scaffold

singulacomp init [project-name] [options] creates a new project directory. The starter writes a v2 singulacomp.yaml and the canonical .singulacomp/opencode system-skill source. The command can wire local coding-tool discovery without changing the cloud OpenCode runtime. The command does not write .singulacomp/link.json. singulacomp ship or singulacomp projects link create that file.

The local coding-tool selection does not change the cloud OpenCode runtime.

singulacomp 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

singulacomp 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: singulacomp deploy.

Each run:

• Parses and validates singulacomp.yaml (skip with --no-verify).
• 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 SingulaComp GitHub App. Any other existing origin is registered as-is. No origin creates a managed SingulaComp git repo.

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 singulacomp sessions chat <id> -p "…" --queue.

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 files reads the working tree the agent is editing right now, before anything is committed; singulacomp 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.

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, SINGULACOMP_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. Gated by the review_center feature flag; turn it on with singulacomp projects features enable review_center.

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 singulacomp 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 SingulaComp substitutes the real value outside it (egress-enforced exposure, and singulacomp secrets call) — is experimental. Enable the secrets_egress feature flag (Settings → Feature flags) to use it; with the flag off, singulacomp 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 singulacomp 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 singulacomp.yaml commit; default and config commit to singulacomp.yaml on the project's default branch. scope needs project.agent.write; default and config need project.customize.write.

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 singulacomp models ls --json. Per-agent pins live on singulacomp agents model <agent> <model-id>. Writes need project.customize.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 singulacomp_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. voice name needs project.customize.write.

Connectors

Connectors an agent calls as tools. add, rm, and policy set edit the local singulacomp.yaml; run singulacomp 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.customize.write.

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

Marketplace

Browse the SingulaComp 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 SingulaComp system skills are the platform's own documentation. They cover sessions, sandboxes, OpenCode, the connector, memory, and channels. The API serves them live, so they match the deployed host version. The binary and a token are enough for an agent to retrieve this context.

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

singulacomp skills is a permanent alias for the same command.

This list is always the system skills, never a mix. Optional skills live in the marketplace: singulacomp marketplace list --type skill.

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: SINGULACOMP_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, or a monitor (experimental). add, rm, enable, disable edit the local manifest — run singulacomp ship to apply. pause/resume flip a separate, server-side switch. See Triggers.

add options: --type <cron\|webhook\|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.

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), and --expires <iso> (auto-revoke timestamp). --principal filters a list, and takes user:<id>, group:<id>, service_account:<id>, or pending:<email>; a bare id is read as a user. 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.

singulacomp access grant --user [email protected] --role manager
singulacomp access grant --user [email protected] --role admin --account
singulacomp access grant --group 8f3c… --role member --project 1a2b…
singulacomp access grant --user [email protected] --agent support-bot
singulacomp 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 SingulaComp; an agent additionally carries SingulaComp CLI scopes in singulacomp.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 its monotonic session_sequence. --all follows every continuation cursor.

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 singulacomp access grant. The older singulacomp roles assign / unassign / assignments verbs still work and write the same table, but singulacomp access is the documented path. singulacomp roles actions is superseded by singulacomp permissions ls.

A custom role only adds permissions. SingulaComp 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 — singulacomp roles create --actions and singulacomp roles set-actions take exactly them. Alias: singulacomp 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. singulacomp access grant --agent <name> writes the same row.

Manifest validation

See Manifest reference.

Self-host

singulacomp self-host runs one Docker-based stack, identical on a laptop, a VPS, or a cloud VM. See Self-hosting and Self-hosting architecture.

Common flags: --instance <name> (default default), --domain <domain>, --tunnel cloudflare, --version/--tag/--release <v>, --channel stable|latest (default stable), --auto-update on|off (default on; forced off by --local-images), --update-time <HH:MM> / --update-tz <tz> (auto-updater schedule), --local-images (run locally-built images; dev mode), --enterprise-license (unlock SSO/SCIM/RBAC/audit), --admin-email <email>, --no-restrict-account-creation (let any signed-in user create new accounts/orgs; default is admin-only), --restrict-account-creation (re-enable the admin-only default), --json, --yes.

Token scope

Every token starts with singulacomp_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