# CLI overview

The `deepspace` command - scaffold, develop, test, and deploy.

The CLI ships inside the `deepspace` package, which is added to every scaffolded app. You run it via `npx`:

```bash
npx deepspace <command> [options]
```

No global install is needed. To create a new app, use `npm create deepspace@latest` - it fetches the latest scaffolder on demand.

## Command index

| Command | Purpose |
|---|---|
| `create` | Shortcut for `npm create deepspace@latest` |
| `login` | Authenticate via GitHub/Google OAuth, or email + password |
| `logout` | Clear the local session |
| `whoami` | Print the current login state |
| `dev` | Run the app locally with Vite + worker in-process |
| `kill` | Stop leaked workerd / wrangler / vite processes |
| `test` | Run the Playwright + Vitest test suites |
| `screenshot` | Capture a screenshot of any URL via Playwright |
| `test-accounts` | Create and manage `@deepspace.test` accounts for testing |
| `add` | Install a scaffold feature (`ai-chat`, `messaging`, `kanban`, ...) |
| `integrations` | Discover and call third-party integration endpoints |
| `managed-repos` | Create and manage DeepSpace-owned GitHub repos |
| `invoke` | Top-level alias for `integrations invoke` |
| `deploy` | Deploy to Workers for Platforms; live at `<name>.app.space` |
| `undeploy` | Tear down a deployed app and its provisioned resources |
| `domain` | Buy, attach, and manage custom domains |
| `library` | Publish (or unpublish) your deployed app in the DeepSpace community library |

[Full command reference →](/cli-reference/commands)

## Login state

Login is shared across every app on the machine. One `npx deepspace login` covers `dev`, `test-accounts`, `deploy`, and billed integration calls for all apps.

```bash
npx deepspace whoami        # human-readable
npx deepspace whoami --json # machine-readable
```

The session file lives at `~/.deepspace/session`. Treat it as secret - never commit it.

## Agent-friendly defaults

The CLI is designed to be safely invoked from automation:

- **Non-interactive by default.** Omitting required arguments prints usage and exits 1 - it does not prompt on stdin.
- **`--json` everywhere it matters.** `whoami`, `domain *`, `integrations list/info`, `test-accounts list` all support machine-readable output.
- **`--yes` skips confirmation prompts** on destructive commands (`domain buy`, `domain detach`, `test-accounts clear`, `managed-repos delete`).
- **Help is plain text.** `--help` / `-h` produces ANSI-free output suitable for scripting.

## Local dev workflow

The standard development loop:

<Steps>
  <Step title="Scaffold">
    ```bash
    npm create deepspace@latest my-app
    cd my-app
    ```
  </Step>
  <Step title="Develop">
    ```bash
    npx deepspace dev
    ```
    Vite + worker run on `localhost:5173` with HMR.
  </Step>
  <Step title="Test">
    ```bash
    npx deepspace test
    ```
    Smoke + API specs run against the dev workers.
  </Step>
  <Step title="Deploy">
    ```bash
    npx deepspace deploy
    ```
    Live at `<name>.app.space` in ~30 seconds.
  </Step>
</Steps>

## Cleaning up leaked processes

If a previous `dev` session crashed or you closed the terminal without `Ctrl-C`, leaked `workerd` / `wrangler` / `vite` processes can hold ports. Use:

```bash
npx deepspace kill                   # default port 5173
npx deepspace kill --port 5180
npx deepspace kill --all             # sweep every workerd/wrangler/vite
```

<Warning>
**Don't kill a parallel session's processes.** If a sibling session is running on port 5173, use `--port 5174` (and update `tests/playwright.config.ts` to match) instead of stopping their dev server.
</Warning>

## Next steps

- [Command reference](/cli-reference/commands) - every command, every flag.
- [Quickstart](/get-started/quickstart) - walk through the full dev loop.