CLI
Find the right CLI command
Navigate command families for files, notebooks, collaborative documents, agents, browsers, and operations.
Discover commands for your installed version
Use help at each level. These commands do not perform the operation they describe:
cocalc --help
cocalc project --help
cocalc project file --help
cocalc project jupyter --help
cocalc browser --help
The table below is a navigation guide, not a promise that every subcommand is
available in every installed release or deployment. Run the relevant command
with --help for its arguments, selectors, defaults, and examples.
Choose a command family
| Task | Start with |
|---|---|
| Find documentation and agent context | cocalc docs --help |
| Sign in, inspect profiles, request fresh authentication | cocalc auth --help |
| Find, select, start, or inspect projects | cocalc project --help |
| List, read, upload, download, and search files | cocalc project file --help |
| Run a shell command or retrieve its asynchronous result | cocalc project exec --help |
| Work with a persistent terminal session | cocalc project terminal --help |
| Inspect, edit, run, and save live notebooks | cocalc project jupyter --help |
| Build supported documents | cocalc project build --help |
| Work with project chats and scheduled agent tasks | cocalc project chat --help |
| Start project Codex work | cocalc project codex --help |
| Inspect and control active Codex sessions | cocalc codex --help |
| Manage workspaces and select one in a browser | cocalc workspaces --help |
| Edit collaborative task documents | cocalc tasks --help |
| Script supported collaborative document APIs | cocalc exec --help |
| Export or import structured document archives | cocalc export --help, cocalc import --help |
| Discover and automate a browser session | cocalc browser --help |
| Inspect or wait for long-running operations | cocalc op --help |
| Browse and copy published shares | cocalc share --help |
| Inspect account resources and notifications | cocalc account --help, cocalc notifications --help |
| Work with membership packages and seats | cocalc membership --help |
| Manage host and compute resources | cocalc host --help, cocalc vm --help |
| Inspect software artifacts and RootFS catalogs | cocalc software --help, cocalc rootfs --help |
| Manage the local CLI daemon | cocalc daemon --help |
| Run local CoCalc distributions | cocalc plus, cocalc launchpad (may install the selected distribution when first invoked) |
Operator and developer surfaces also include admin, bay, rocket,
cloudflare, dev, load, persist, legacy-migration, and
migrate. These have different permissions and side effects from ordinary
project work. Begin with their help and the relevant operator documentation.
Three different ways to execute code
| Command | Where the code runs | Typical use |
|---|---|---|
cocalc project exec |
A process inside the selected project | Run existing software or a script; use --bash when shell interpretation is needed. |
cocalc exec |
The local CLI process, with a typed api object that accesses CoCalc services |
Work with supported collaborative documents and workspaces. |
cocalc browser exec |
A constrained scripting environment controlling a browser session | Inspect or act on the browser through its exposed API. |
For the backend API declaration bundled with your CLI:
cocalc exec-api
Its supported namespaces include api.tasks, api.text,
api.timetravel, api.export, api.import, and api.workspaces.
For a text document open collaboratively in CoCalc, inspect api.text before
replacing the file on disk. For notebooks, start with project jupyter
instead of editing raw notebook JSON.
For the browser API declaration provided by a running browser session:
cocalc browser exec-api --help
Follow that command's target options to retrieve the declaration for your
session. The constrained QuickJS mode is not an unrestricted page JavaScript
console: window, document, and top-level await are unavailable.
Trusted development sessions may expose a richer runtime when site policy
permits it. Inspect the actual declaration; use the exposed API and command
examples rather than assuming either runtime.
Find documentation and stable UI actions
cocalc docs search "notebook"
cocalc docs skill-context --query "project secrets"
cocalc docs actions --executable
cocalc docs action settings.environment.secrets
docs skill-context prints selected documentation for an agent; it does not
install or update an agent skill. docs action describes an action without
executing it. Browser commands can execute supported action IDs after you
resolve an appropriate browser target.
The CLI's bundled docs and backend declaration describe the installed build. A browser declaration comes from a running session and can differ. If a command or method is missing, compare the installed CLI, server, and browser versions before treating the difference as an authentication failure.
Follow a complete recipe
- Edit collaborative text with the CLI
- Run and save notebooks with the CLI
- Test browser workflows with the CLI
- Schedule agent tasks with the CLI
- Manage workspaces and notices with the CLI
- Build documents and track CLI versions
Before automating a workflow
Complete the quickstart, confirm authentication and targets, and use the result checks for scripts. Keep returned operation IDs and document revisions when a workflow needs to recover or continue later.