Install the CLI

Everything you do with Stackbone runs through one command-line tool called stackbone. On this page you install it and sign in, which takes two commands.

Before you start

Four things to have ready:

You need	Why
Node.js 24	Stackbone runs on Node. Node 24 covers the whole local loop.
pnpm	Stackbone workspaces use pnpm. Turn it on with `corepack enable` (it ships with Node).
Docker	Your workspace starts a small local database when you run it.
A free account	Sign up at app.stackbone.ai.

Note

The CLI runs on macOS, Linux, and WSL2 on Windows. If you're on Windows, install WSL2 first (wsl --install -d Ubuntu), then run every command from inside the Ubuntu terminal. PowerShell and CMD stop the CLI at startup with a message pointing you there, and Git Bash works as well.

In Git Bash, Ctrl+C reaches a long-running command only through winpty, which Git for Windows ships. The CLI re-runs itself under winpty when it needs to. If winpty is not on your PATH, the CLI says so and you start the local runtime as winpty stackbone dev instead.

Install the command

The fastest way is pnpm dlx, which downloads the tool on demand so you install nothing:
```
pnpm dlx @stackbone/cli --help
```
If you'd rather have stackbone always available, install it once globally:
```
pnpm add -g @stackbone/cli
stackbone --help
```
Note
Either way works for the rest of this guide. The examples write stackbone, so if you skipped the global install, put pnpm dlx @stackbone/cli in front of each command instead.
Sign in

Sign in with your email. There are no passwords:
```
stackbone login
```
The CLI prints a short code, opens your browser on the page that carries it, and waits there until you answer:
```
◆◆◆ stackbone v0.3.3 · login

Authorise this CLI in your browser
  Code: VRFL-CRCN
  URL: https://app.stackbone.ai/cli?user_code=VRFLCRCN
  Expires: in 5 min

Opening your browser…
Approved

Logged in as you@company.com
```
Check that the code on the page is the code in your terminal, then choose Approve.

The approval page. It needs a signed-in browser, so on a new machine it asks for your email first and comes back here with the code.

The terminal picks up the approval on its own. You can close the tab.

The code lasts five minutes. If it runs out, the CLI stops with Device code expired before approval and stackbone login mints a new one. The CLI saves the session on your machine, so you sign in once per machine.
Note
On a server with no browser, add --no-browser and open the printed link from your phone or laptop instead:
```
stackbone login --no-browser
```
The CLI also switches to that mode on its own when it sees CI, SSH_CLIENT, or SSH_TTY in the environment.

Check it worked

Confirm you're signed in:

stackbone whoami
# user:         you@company.com
# user id:      f81d4fae-7dec-4e6b-a1c5-2f4e0b7a9c31
# organization: Acme (acme)
# endpoint:     https://api.stackbone.ai

If your email and organization print, you're signed in.

Pick the organization

That organization line is the one every workspace you create belongs to. If you are a member of more than one, list them and switch:

stackbone list
# SLUG        NAME        ID
# acme        Acme        019e92f9-a90d-73af-b0ef-d6a0dce01ed6
# acme-labs   Acme Labs   97e95d64-7bbf-465d-8582-95b8d8246e2c

stackbone organization use acme

Run stackbone organization use with no slug to pick from a list.

Where the session is kept

The CLI writes the session to ~/.stackbone/credentials.json, with file permissions only you can read. It holds one session per control plane, so the same machine can stay signed in to Stackbone's cloud and to a deployment of your own at the same time. stackbone logout ends the active one. The configuration reference covers that file and the STACKBONE_API_URL variable that picks which control plane a command talks to.

If something goes wrong

What you see	What to do
`Device code expired before approval`	You had five minutes. Run `stackbone login` again for a fresh code.
`Login was denied in the browser`	Someone chose Deny. Run `stackbone login` and approve it this time.
The browser never opens	Run `stackbone login --no-browser` and open the printed URL yourself.
The approval page asks you to sign in	Expected on a browser with no session. Sign in by email and the page comes back with the code.
`No organization available for the current user`	Your account has no organization yet. Ask a teammate to invite you, or contact support.
A warning that your CLI is older than the platform	Upgrade with `pnpm add -g @stackbone/cli@latest`.

Every command also takes --json, which prints the same result as a machine readable envelope carrying an error.code and an error.suggestion you can act on.

What's next

Create your workspace: one command builds the folder that holds your agents and workflows.