Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.deep.space/llms.txt

Use this file to discover all available pages before exploring further.

You don’t install DeepSpace globally. The CLI ships inside the deepspace package, which is added to every new app by the scaffolder. The only thing you need on your machine ahead of time is Node.js.

​
Prerequisites

  • Node.js 20 or later. Verify with node --version. If you need to upgrade, use nvm or download an installer from nodejs.org.
  • npm, pnpm, or yarn. Examples in these docs use npm; substitute your favorite if you prefer.
  • A GitHub or Google account. Used for signing in to the CLI and your deployed apps. There’s no separate DeepSpace account.
You do not need a Cloudflare account. DeepSpace deploys to a shared Workers for Platforms namespace operated by the platform. If you want a custom domain, you’ll buy it through the CLI (Cloudflare Registrar or Porkbun under the hood) - no DNS setup on your side.

​
Create a new app

npm create deepspace@latest my-app
cd my-app
This:
  1. Downloads the latest create-deepspace package on demand (no global install).
  2. Scaffolds a Vite + React app with the worker and Durable Objects pre-wired.
  3. Installs deepspace and the starter’s dependencies.
  4. Initializes a git repository.
The scaffold takes about 30 seconds. You’ll have a working app at the end, but npx deepspace dev won’t start until you’ve logged in.

​
Scaffold options

# Interactive prompt-driven mode
npm create deepspace@latest -- --interactive

# Scaffold into the current directory (must be near-empty)
mkdir my-app && cd my-app
npm create deepspace@latest .

# Print help
npm create deepspace@latest -- --help
“Near-empty” means the target directory contains only boilerplate (.git, .gitignore, LICENSE, any *.md, etc.). Anything else triggers a guardrail to prevent overwriting an existing project.
The scaffold drops a CLAUDE.md at the project root that points coding agents at the DeepSpace skill. If you build with Claude Code, Cursor, or another agent, install it once so your assistant uses real SDK signatures instead of guesses:
npx skills@latest add deepdotspace/deepspace-skill

​
Log in to the CLI

Every CLI command that talks to the platform - dev, deploy, invoke, test-accounts, and the rest - requires a session. Plan to log in once before your first npx deepspace dev. 
npx deepspace login
This opens your default browser for OAuth and waits for up to 10 minutes. After you authorize, the CLI writes two files into ~/.deepspace/:
  • ~/.deepspace/session - the long-lived refresh token used to mint new JWTs.
  • ~/.deepspace/token - the current short-lived JWT, refreshed automatically by other commands.
The same session covers every DeepSpace app on the machine - you don’t log in per project. Check your login state: 
npx deepspace whoami
npx deepspace whoami --json   # machine-readable
whoami refreshes the short-lived JWT on demand, so an expired token is handled silently. If ~/.deepspace/session is missing, it prints “Not logged in.” and exits 1. If the session can no longer be refreshed, it prints “Session expired.” and exits 1. In either case, re-run npx deepspace login. Manage your account, deployed apps, billing, and earnings at dashboard.deep.space. The CLI and the dashboard share one session - signing in once covers both.
The session file holds a long-lived refresh token. Treat ~/.deepspace/session, ~/.deepspace/token, and your app’s .dev.vars file as secret. Never commit any of them to version control.

​
Update the SDK

DeepSpace ships frequently. To pull in the latest SDK and CLI, run: 
npm install deepspace@latest
The CLI and the SDK are the same package - bumping the version updates both.

​
Verify your setup

You’re ready to build when all of these succeed: 
node --version             # v20.x or higher
npm create deepspace@latest -- --help
npx deepspace --version
npx deepspace whoami       # prints your account, after `login`

​
Next steps