Sign a terminal in once, then list and make apps, link a folder to one, and manage its keys, the way the railway and supabase CLIs work.
Terminal
npx @soba-so/cli login
login opens your browser once. You check the code matches and press Sign in this
terminal, and the terminal keeps a personal access token in ~/.soba/cli.json,
readable by you only. Then it links the folder you are in: pick a workspace and an
app, or + New app. Its keys go into .env.local, never through a clipboard, a
chat or the terminal's output.
Every other command uses that token through the management
API, with exactly what you may do in each
workspace. So link in a second project does not open the browser again.
Commands#
| Command |
|
login |
Sign this terminal in, then link this folder. --no-link skips the link |
logout |
Sign out, and revoke this terminal's token on the server too |
whoami |
Who this terminal is signed in as |
workspaces |
Your workspaces, and whether you can create apps in each |
apps |
Your apps, by workspace. --workspace shows one |
apps create <name> |
Make an app. Counts against the workspace tier's app limit |
apps rename <app> <name> |
Rename one |
apps delete <app> |
Delete one and everything in it: users, machines, runs, plans, keys. Asks you to type its name, or pass --yes. The workspace's only app cannot be deleted |
link |
Pick an app (or make one). Writes SOBA_KEY, SOBA_PROD_KEY and SOBA_APP_ID to .env.local |
unlink |
Remove those from .env.local. The keys stay valid until revoked |
keys |
The linked app's live keys, as previews |
keys create |
Mint a secret key into .env.local: --environment development (the default) or production |
keys revoke <id> |
Revoke one, by the id soba keys shows |
workspace-key |
Write SOBA_WORKSPACE_KEY: a key for a server that makes apps (below) |
env |
Which app and keys this folder uses, by their first characters |
init |
Link if this folder has no key yet, then print the line to give your coding agent |
An app is named by its name, its slug or its id. A name that two of your workspaces
both use is refused with both ids, rather than guessed.
Options#
| Option |
|
--workspace <name> |
The workspace, instead of being asked |
--app <name> |
The app, instead of being asked or reading SOBA_APP_ID |
--new <name> |
With login or link: make a new app with this name and use it |
--environment <env> |
With keys create: development or production |
--replace |
With keys create: revoke the never-used key for that environment and mint another |
--yes |
With apps delete: do not ask |
--headless |
Print the sign-in link instead of opening a browser |
--env-file <path> |
Where keys go. Default .env.local; a Cloudflare Worker wants .dev.vars |
--url <url> |
The Soba to use. Default https://soba.so, or SOBA_URL |
With nobody at the terminal#
CI, a coding agent, anything without a person to answer: the CLI never waits on a
question it cannot ask. A choice it would have asked about ends the command with the
flag it needs and the options there are, so the next attempt can pass it:
Terminal
npx -y @soba-so/cli login --no-link # the person approves in the browser
npx -y @soba-so/cli apps # see what there is
npx -y @soba-so/cli link --workspace Acme --app "Study planner"
npx -y @soba-so/cli link --workspace Acme --new "Study planner" # or make it
SOBA_ACCESS_TOKEN in the environment is used instead of ~/.soba/cli.json, for a
pipeline that should not sign in at all.
Keys, and which goes where#
SOBA_KEY is a development key, for your machine: it reaches only your users'
own AI. In production, set SOBA_KEY to the value of SOBA_PROD_KEY in your host's
environment. See Environments.
There is one never-used secret key per app and environment. link replaces the one
it made last time if nobody used it; keys create refuses instead, unless you pass
--replace, because a key nobody has used yet may be one you are about to deploy.
Signing out, and expiry#
A terminal's token signs itself out after 90 days without use, and every use
moves that day back, so a terminal you work in never expires. soba logout revokes it
at once; so does Revoke under Account → Sign-In and Security → Terminals,
which lists every terminal signed in as you.
Workspace keys#
Terminal
npx @soba-so/cli workspace-key --workspace Acme
writes SOBA_WORKSPACE_KEY: a key for one workspace, for a server that turns each
thing it builds into a Soba app. It reaches the same management API as your token,
as an admin of that workspace, except that it cannot delete apps or make another
workspace key. Only someone who can both create apps and manage keys there can make
one. Revoke it on the workspace's Settings page. In code it goes to
SobaManagement.