--- title: 'Install the CLI' description: 'Get the stackbone command on your machine and sign in with your email.' position: 2 --- # 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](https://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 and sign in
1. **Install the command** The fastest way is `pnpm dlx`, which downloads the tool on demand so you install nothing: ```sh pnpm dlx @stackbone/cli --help ``` If you'd rather have `stackbone` always available, install it once globally: ```sh 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. 2. **Sign in** Sign in with your email. There are no passwords: ```sh stackbone login ``` The CLI prints a short code, opens your browser on the page that carries it, and waits there until you answer: ```text ◆◆◆ 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 browser page titled "Authorise the Stackbone CLI", showing the verification code and the Approve and Deny buttons.](/images/first-steps/cli-approve.png) _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 browser page confirming "Your CLI is connected".](/images/first-steps/cli-connected.png) _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: > > ```sh > 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. 3. **Check it worked** Confirm you're signed in: ```sh 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: ```sh 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](/docs/cli/reference/configuration) 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](/docs/home/get-started/first-workspace)**: one command builds the folder that holds your agents and workflows.