Reference
CLI reference
Every robodev command.
Package name: robodev. Tokens live in ~/.robodev/credentials.json. The current folder is linked via robodev/.robodev. What changed in each release: Changelog (/docs/changelog).
robodev auth
Opens the Starbase OAuth page, listens on a localhost callback, and stores access + refresh tokens.
robodev logout
Deletes ~/.robodev/credentials.json.
robodev whoami
Prints the signed-in email and user id.
robodev projects
Lists projects you can access as id, name, and API URL. Rename or delete a project from the dashboard if you are an organization admin.
robodev create [path] [--template <id>] [--starter <id>] [--empty] [--org <id>]
Resolves a starter, then creates a Starbase project named after the folder, copies that starter, writes robodev/.robodev plus VITE_API_URL and VITE_PUBLIC_API_URL, deploys, and runs pnpm install at the project root. Default Empty includes a hosted Welcome page and does not write a frontend block. Space, Auth chat, and Marketplace also write a frontend block and try a local Vite build before deploy; a failed FE build still deploys schema + APIs. Those starters print bun next steps. Empty prints hosted Welcome / robodev dev / pnpm run dev:fe next steps. Shadcn prints the same plus pnpm run generate:api. Refuses to overwrite an existing package.json, robodev/database.ts, robodev/.robodev, or legacy database.ts / .robodev.
- Without --template, --starter, or --empty, the starter is empty (TTY and non-TTY). No numbered list is shown.
- --template <id> or --template=<id> selects that starter and skips the prompt. --starter is a full alias.
- Bare --template / --template= (or --starter / --starter=) on a TTY shows the numbered catalog. Accept a 1-based index or an id.
- Bare --template / --starter when stdin is not a TTY exits 1 with robodev create --template requires a starter id when stdin is not a TTY. then usage().
- --empty is an alias for --template empty / --starter empty and includes the hosted Welcome page.
- Any two of --empty, --template, or --starter exits 1 with Use only one of --empty, --template, or --starter.
- Unknown --template / --starter, empty prompt, unknown number, or unknown id exits 1 with Valid ids: space, auth-chat, marketplace, backend, empty, shadcn.
- --org <id> or --org=<id> creates the project in that organization and skips the org prompt, even on a TTY. Allowed together with --template, --starter, or --empty.
- On a TTY without --org, if you are an admin of two or more organizations, a numbered list of admin orgs is shown. Accept a 1-based index or an org id.
- Without a TTY and without --org, or with exactly one admin org, the organization id is omitted so the API uses your oldest admin organization.
- Unknown organization prompt, empty answer, or unknown id exits 1 and does not create a project. Developer-only memberships are not listed.
- Unknown other create flags and a missing value after --org also exit 1. --empty=… is an unknown flag. --organization is not a flag.
robodev link [projectId]
Writes robodev/.robodev, VITE_API_URL, and VITE_PUBLIC_API_URL for an existing project. Preserves an existing frontend block or frontend: false. If frontend is absent and apps/fe/package.json exists, writes the default frontend block. Omit the id to pick from a list.
robodev deploy [--force] [--name <name>] [--org <id>]
Replace-alls project source from the winning disk layout (Tiny apps/fe + packages/be, or CLI robodev/ / root src/) and writes the live host snapshot (compiled APIs + Vite dist as index.html + public/**). A CLI database.ts wins over leftover Tiny paths. When .robodev frontend is set, runs the local Vite build first and aborts on failure. After a successful apply, waits until the project host is live before printing App and Docs URLs. If the host does not become reachable within 30 seconds, the command fails without printing the success banner. Use --force to apply destructive schema changes without a prompt. Auth is ROBODEV_DEPLOY_KEY, else file deployToken, else robodev auth. A key requires an existing link and never creates a project. If the folder has no robodev/.robodev and no key, deploy creates and links a hosted project from the local files (name-only POST, no starterId) after you are signed in and the tree collects.
- Linked folders ignore --name and --org and deploy as usual.
- Unlinked TTY (JWT only): asks for an organization when you admin two or more, then a project name (folder basename is the default, capped at 80).
- Unlinked non-TTY (JWT only): pass --name (and --org when the default org is wrong). Without --name the command exits 1 and does not create. The message tells you to pass --name / --org or run robodev link / robodev create.
- Unlinked + deploy key: exits 1 with no POST /v1/projects. A key cannot create projects; provide robodev/.robodev with projectId and apiUrl.
- Collect failure (missing robodev/database.ts / database.ts, or other collect errors) exits 1 before POST /v1/projects.
- If create succeeds and deploy fails, robodev/.robodev stays so a retry does not create a second project.
- --name <name> or --name=<name>, --org <id> or --org=<id> (same org rules as create). Unknown flags exit 1.
- robodev-be deploy is backend-only and still needs a deploy key.
- If the connection drops or Starbase answers 5xx, the deploy may still have finished on the server. The error is followed by: The deploy may still have finished on the server. Check with: robodev logs --deploy.
- Errors name what went wrong: Starbase returned 502 Bad Gateway (request id: req_…): <start of the body> for a non-JSON answer, Could not reach <url>: <reason> when the server is unreachable. Quote the request id when you report a problem. ROBODEV_DEBUG=1 adds a stack trace.
robodev load
Downloads the project's source workspace onto this folder so local files match the hosted source. Requires robodev auth and an existing robodev/.robodev (or legacy .robodev). Does not create or link a project. Overwrites allowed source files without a prompt, including apps/fe/**, and deletes local collectables that are not in the payload (walks into apps/). Never writes or deletes .env, .robodev / robodev/.robodev, or credentials. Does not download the host dist snapshot. Empty source exits 1 and writes nothing. Preview → More → Download zip is the dashboard equivalent of this source listing.
- No flags. Unknown flags and extra arguments exit 1.
- No source (or every file skipped) exits 1 and writes nothing.
- GET /v1/projects/:id/workspace — source files only, not GET /deployment/files.
robodev logs [--limit <n>] [--follow|-f] [--status 2xx|4xx|5xx] [--json] [--project <id>]
robodev logs --deploy [<logId>] [--follow|-f] [--json] [--project <id>]
Prints the hosted project's request logs, or with --deploy its deploy logs. Auth is the same as deploy: ROBODEV_DEPLOY_KEY, else file deployToken, else robodev auth. A deploy key reads only its own project's logs. The project is --project, else the linked one; with neither the command exits 1 with Not linked. Run robodev link or pass --project <id>.
- Request logs: the newest --limit rows (default 50, 1–200), oldest first, one per line: time, status, method and path, duration, request id, then the error code and message when the request failed, and via mcp tool=<name> for MCP calls.
- --status 2xx|4xx|5xx filters. --json prints the raw rows as JSON lines.
- --follow keeps polling every 2 seconds and prints only new rows until Ctrl-C. Rows are written in batches, so they can arrive a few seconds late.
- --deploy prints the latest deploy: a header (id, status, source and actor, start time, duration, error) and its transcript. --deploy <logId> prints that deploy. With --follow on a running deploy, new transcript lines stream until it finishes. No deploys prints No deploys yet.
- Exits 0 whenever the log was fetched, whatever the deploy's own status.
- Worker console output (console.log in your handlers) is not stored. Boot failures appear in the deploy log.
- A Starbase that predates deploy-key log reads answers a key with This Starbase does not allow deploy keys to read logs yet. Run robodev auth, or upgrade Starbase.
robodev restart [--json] [--project <id>]
Restarts the hosted project's worker. Secret changes already restart a running isolated worker automatically, so use this to retry after a failed automatic restart (robodev secrets list reports one). Isolated workers read secrets when they start; a fresh worker boots with the current secrets and the old one keeps serving until it is healthy. Auth and project resolve like robodev logs: ROBODEV_DEPLOY_KEY, else file deployToken, else robodev auth with the linked project or --project.
- Success prints Worker restarted (generation N). Secrets are now current. and exits 0.
- In-process projects print Not needed — this project runs handlers in-process and reads secrets on every request. and exit 0.
- A worker that is not running prints Not running — the next request starts it with current secrets. and exits 0.
- While a deploy runs it prints A deploy is running — it will apply current secrets. and exits 1.
- If the new worker fails to boot it prints Worker failed to start: <message>. The previous worker is still serving. See: robodev logs --deploy <logId> and exits 1. The failed restart is listed on the Deployments page.
- --json prints the response body.
- A Starbase without restart support prints This Starbase does not support restart yet. Upgrade Starbase. and exits 1.
robodev secrets list [--json] [--project <id>]
Manages the hosted project's Secrets (ctx.env). Auth and project resolve like robodev restart: ROBODEV_DEPLOY_KEY, else file deployToken, else robodev auth with the linked project or --project. Values are write-only and never printed. list prints NAME updated <ISO> per secret, or No secrets.; --json prints { secrets, autoRestart }. When the last automatic worker restart failed, list also prints to stderr The last automatic worker restart failed: <reason>. The previous worker is still serving. See deploy log <id>. Run robodev restart to retry. and still exits 0. See Secrets (/docs/secrets).
robodev secrets set NAME [--value-file <path>] [--restart] [--json] [--project <id>]
- Reads the value from --value-file <path>, else from stdin when it is piped, else from a hidden prompt (Value for NAME: ). One trailing newline is stripped from a file or stdin, so echo "$KEY" | robodev secrets set KEY works. An empty value exits 1 with Secret value is empty.
- A value on the command line (set NAME=value, --value) exits 1 before any request: Do not pass secret values on the command line (they end up in shell history). Pipe the value on stdin, type it at the prompt, or use --value-file <path>.
- Prints Set secret NAME on project <id>. The value is stored encrypted and is never shown again. The second line is The running worker restarts automatically within a few seconds to pick it up. when Starbase scheduled the restart (a running isolated worker), else Handlers read it on the next request.
- --restart is deprecated: Starbase restarts the worker on its own, so the flag calls nothing, prints --restart is no longer needed: the worker restarts automatically after a secret change. to stderr, and exits 0. Against an older Starbase (no restartScheduled in its answer) it still restarts after the change as in robodev 0.72.
- --json prints the server's answer { name, createdAt, updatedAt, restartScheduled, restartNeeded }; restart is added only in the older-Starbase fallback.
robodev secrets delete NAME [--restart] [--json] [--project <id>]
- Prints Deleted secret NAME from project <id>. and the same second line as set. A name that does not exist exits 1.
- --restart and --json work as for set; --json prints { ok, restartScheduled, restartNeeded }.
robodev dev [--port <n>] [--db-port <n>] [--database-url <url>] [--db-superuser] [--force] [--no-watch] [--with-fe] [--tunnel]
Runs the project on your machine without a Starbase account or hosted project. Finds the backend (database.ts, robodev/database.ts, or packages/be/database.ts, walking up from the current folder), starts an embedded Postgres persisted under .robodev/dev/pg, compiles and pushes the schema, then serves file routes, Robodev Auth (including Google via the platform broker), jobs (ctx.jobs.enqueue and defineJob cron on reserved robodev_jobs tables), sockets on ws://localhost:{port}/sockets/…, storage (bytes in .robodev/dev/storage, GET /storage/objects/{key} returns 200), /openapi.json, Swagger, and a dashboard at /_robodev on http://localhost:4000. Watches the backend tree and reloads on save; a successful reload closes sockets with 1012 deployed; a compile error keeps the previous build serving. Destructive schema changes are printed and skipped until --force. See Offline dev (/docs/dev).
- --port <n> — API port (default 4000).
- --host <address> — interface to bind (default 127.0.0.1, or ROBODEV_DEV_HOST). The dev dashboard and DB browse have no authentication, so only bind 0.0.0.0 on a network you trust.
- --db-port <n> — Postgres port (default 0, meaning pick a free one).
- --database-url <url> — use an existing Postgres instead of the embedded one. Skips role handling.
- --db-superuser — run app queries as the embedded superuser. By default they run as the restricted robodev_app role, like the hosted project role, so TRUNCATE on a public table fails locally as it does hosted. See Offline dev (/docs/dev).
- --force — apply destructive schema changes.
- --no-watch — compile once and serve.
- --with-fe — also start apps/fe with VITE_API_URL, VITE_PUBLIC_API_URL, and APP_PUBLIC_API_URL set to the local API.
- --tunnel — expose only the API port at https://<id>.tunnels.robodev.povio.dev. Writes that URL to robodev/.robodev as tunnelUrl. Does not expose the frontend. See Offline dev (/docs/dev).
- ctx.llm, ctx.agent, and ctx.push throw llm_not_configured / llm_not_configured / push_not_configured offline. ctx.jobs, ctx.storage, and ctx.sockets run locally. ctx.pdf.fromHtml hops to Starbase. ctx.email prints to the terminal; ctx.env comes from a root .env file.
robodev openapi [--out <file>]
Prints the same OpenAPI spec robodev dev serves at /openapi.json, without a database. Finds the backend the way robodev dev does, compiles and loads it, and writes pretty JSON to stdout, or to <file> with --out (parent folders are created, and Wrote <file> goes to stderr). It starts no Postgres, needs no robodev auth or linked project, and makes no network calls, so it works in sandboxes where robodev dev cannot start. Load warnings, compile errors, and console.log from your modules go to stderr, so stdout is only the JSON. A compile or load error exits 1 and writes nothing. Builds into .robodev/dev/openapi-build, so it is safe to run while robodev dev is running.
robodev tunnel <port>
Exposes any local port at https://<id>.tunnels.robodev.povio.dev, including from a folder that is not a project. This is how you expose port 3000 or anything other than the API port that robodev dev --tunnel publishes. The id is unguessable and is remembered in ~/.robodev, one per port, so the next run of the same port reuses the URL. No login. Anyone with the link can call it. The tunnel exists only while the command is running; when it stops, the URL stops answering until the next start. If that id is already connected from somewhere else, the new start is refused and does not take over.
robodev tunnel rotate
Writes a new unguessable id into the same file the current tunnel uses, prints the new https URL, and stops the old URL. In a project directory this updates tunnelUrl in robodev/.robodev (what robodev dev --tunnel reads). Outside a project it updates the remembered port in ~/.robodev (what robodev tunnel <port> reads); when several ports are remembered, pass the port: robodev tunnel rotate 3000. The next start uses the new id.
Environment
- STARBASE_URL — control-plane API and the offline PDF hop (default https://robodev.povio.dev). See PDF (/docs/pdf).
- STARBASE_FE_URL — browser UI for OAuth (defaults to STARBASE_URL).
- ROBODEV_DEPLOY_KEY — project deploy key for robodev deploy, robodev logs, robodev restart, robodev secrets, and robodev mcp (publish and secrets; not reading source or auth users). Wins over file deployToken. Does not authorize robodev load. See Deploy (/docs/deploy).
- ROBODEV_DEBUG=1 — print stack traces and error causes when a command fails.