decocms/studio/decocms-studio

Operate deco Studio

Every call goes through the decocms CLI, which holds the user's OAuth session and refreshes it. The CLI is the only thing that touches the token: call Studio with decocms api and decocms tools, and leave the session files in the data dir alone.

Run the CLI as decocms when it is on PATH, otherwise bunx decocms@latest. An Unknown command: tools error means a cached old version; rerun with bunx decocms@latest.

The CLI runs on Bun, also when started with npx. If bunx is not found, ask the user before installing Bun with curl -fsSL https://bun.com/install | bash (Windows: powershell -c "irm bun.com/install.ps1 | iex"), then call ~/.bun/bin/bunx until a new shell has it on PATH.

1. Session

decocms auth whoami        # prints Target and User when logged in

When whoami or any call says Not logged in or Could not refresh session, give the user the decocms auth login command it prints to run in their own terminal (it opens a browser for them to approve), wait for them, then retry. The session refreshes itself, so this is normally needed once per machine. Do not work around a missing session with API keys, MCP tokens or presigned URLs. A self-hosted or local studio adds --target <url> to every command, e.g. --target http://localhost:3000.

Done when whoami prints the user the person expects. Its Target is the studio origin used in the links below.

2. Organization slug

Every org-scoped call needs the organization's slug, the first path segment of a studio URL (https://studio.decocms.com/<slug>/...). List the user's organizations and pick the one they mean; ask when several fit:

decocms orgs           # slug<TAB>name per organization; --json adds ids

When the user names a project instead of an org, search across their orgs: decocms api "/api/_me/projects/search?q=<term>" returns each match's orgSlug.

3. Builtin tools first

Tools are the main surface: the web app calls the same ones. Each tool's input schema is the documentation, so look it up instead of guessing fields.

Org files are the exception: use the fs routes in section 4. They cover listing, moving and sharing, which no tool does.

decocms tools list --org <slug> thread            # NAME<TAB>summary, filtered
decocms tools describe COLLECTION_THREADS_LIST --org <slug>   # full JSON schema
decocms tools call COLLECTION_THREADS_LIST --org <slug> -d '{"limit":5}'
decocms tools call <NAME> --org <slug> -d @args.json          # or -d @- for stdin

call prints the tool's JSON result and exits non-zero on failure, with the error body still on stdout:

• 400 {"error":"Invalid input","issues":[...]}: fix the arguments against describe.
• 403 {"error", "code"?}: the user lacks the permission, or a code names a

plan or budget refusal. Report it; a retry gets the same answer.

• 404 Unknown tool: the name is wrong; search with tools list.

Read annotations in describe before calling: destructiveHint: true (delete, remove, overwrite) needs the user's explicit go-ahead for that specific call.

4. REST routes

Some features have no tool: the org filesystem (the Library), sending a message to an agent and streaming its reply, object storage bytes, thread outputs, and the event stream. Reach them with decocms api, which works like gh api:

decocms api "/api/<slug>/fs/home/list?path="
decocms api "/api/<slug>/fs/home/file?path=notes/a.md" -X PUT -H "Content-Type: text/markdown" -d @a.md

-d takes a literal, @file, or @-; with -d the method defaults to POST. Literals and stdin are sent as JSON and @file by its extension; -H overrides. Paths must start with / on the session's studio. Read rest.md for each route's contract before calling it.

5. Library files

A file is in the Library once GET fs/<vol>/stat returns its entry; check that before telling the user it is there. Then link it, with <target> from whoami and the query values URL-encoded:

• In Studio: <target>/<slug>/library?path=<vol>/<folder>&preview=<vol>/<path>
• Direct link: <target>/api/<slug>/fs/<vol>/read?path=<path>. It opens only

for org members until the file is shared.

Share a file only when the user asks, and confirm the mode first: public lets anyone with the link read it, password asks for a password you set and hand back to the user. See POST fs/<vol>/public in rest.md.

Vocabulary

• thread: what the UI calls a chat. Tools and routes use thread.
• agent: a virtual MCP (COLLECTION_VIRTUAL_MCP_*, ids like vir_...).

The org's default agent is Decopilot, id decopilot_<orgId>.

• connection: an MCP server registered in the org (COLLECTION_CONNECTIONS_*).
• volume: a top-level folder of the org filesystem (home, outputs, uploads).