# CLI Guide

> Use the public npm CLI with a StaticX token to log in, create sites, deploy builds, inspect logs, and stay inside the same /api/v1 contract.

Canonical: https://staticx.site/documentation/cli

Public npm CLI

## Run StaticX from a terminal with the same token-protected API contract.

 The public `staticx` CLI is a friendly wrapper around `/api/v1`. Install it, log in once with a bearer token, then create sites, deploy builds, and inspect logs without leaving your shell.

 

 ```
npm install -g staticx

staticx login --base-url "https://staticx.site/api/v1" --token "STATICX_API_TOKEN"
staticx guide
staticx whoami
staticx create --name "Marketing Site" --versioning off
staticx deploy --site-id SITE_ID --dir dist --versioning off
staticx domain --site-id SITE_ID --domain app.example.com
```

  Machine-readable sources

## Give the CLI the same contract the agents use.

 StaticX publishes a short LLM index, a full agent playbook, and an OpenAPI contract. Keep these in sync with the CLI, dashboard, and MCP docs.

 

 [ TXT **llms.txt** Compact index for agents and crawlers. ](https://staticx.site/llms.txt) [ TXT **llms-full.txt** Expanded playbook with prompts, curl, and safety rules. ](https://staticx.site/llms-full.txt) [ JSON **openapi.json** Canonical API schema with the `/api/v1/openapi.json` alias. ](https://staticx.site/openapi.json) 

  Golden deploy prompt

## Use one prompt when handing a deploy to an agent.

 

 Prompt 

 ```
Deploy `dist` to StaticX project `SITE_ID` using `STATICX_API_TOKEN`.

Use:
- https://staticx.site/llms.txt
- https://staticx.site/llms-full.txt
- https://staticx.site/api/v1/openapi.json

Build, validate `index.html` + `404.html`, apply StaticX form rules if forms exist, zip `dist` root, upload, deploy, check logs, then return https://your-site.staticx.store or the exact API error. Use `staticx deploy --versioning off` only when the user wants one baseline release instead of rollback history. Never expose the token.
```

 

  Where to generate tokens

## Create the token from the surface that matches the job.

 

### Global token

Open **Settings → API tokens** when one operator or internal tool needs account-wide access.

Best for: listings, dashboards, broad internal automation.

 

### Site token

Open **Project Settings → Agent deploy** when the CLI only needs one site.

Best for: CI runs, deploy bots, one-off release jobs.

 

### Workspace token

Open **Workspace → Agent deploy** when one runner must stay inside one workspace.

Best for: multi-site client workspaces, team release tools.

 

 

  Ready-made command sets

## Use the smallest scope that still lets the CLI finish.

 

 Global

Best when one operator needs account-wide visibility before creating or listing sites.

 

 ```
npm install -g staticx

staticx login --base-url "https://staticx.site/api/v1" --token "STATICX_API_TOKEN"
staticx guide
staticx whoami
staticx workspaces
staticx create --workspace-id WORKSPACE_ID --name "Marketing Site"
```

  Workspace

Best when the runner must stay inside one workspace but still create or inspect multiple sites there.

 

 ```
npm install -g staticx

staticx login --base-url "https://staticx.site/api/v1" --token "STATICX_API_TOKEN"
staticx guide
staticx whoami
staticx sites --workspace-id WORKSPACE_ID
staticx create --workspace-id WORKSPACE_ID --name "Client Site"
```

  Site

Best for the smallest release scope when the CLI only needs deploy and log access to one site.

 

 ```
npm install -g staticx

staticx login --base-url "https://staticx.site/api/v1" --token "STATICX_API_TOKEN"
staticx guide
staticx whoami
staticx create --name "Marketing Site" --versioning off
staticx deploy --site-id SITE_ID --dir dist
staticx deploy --site-id SITE_ID --dir dist --versioning off
staticx domain --site-id SITE_ID --domain app.example.com
staticx domain-status --site-id SITE_ID
staticx logs --site-id SITE_ID
```

  

  Custom domains

## Start manual custom domain setup from the terminal.

 Use this when a deploy bot, AI agent, or operator needs to move a site to a customer domain without opening the dashboard. The command prints one DNS record. Create that record, then StaticX checks it and activates SSL automatically. If the user wants StaticX to create DNS inside an external provider account, they must approve DNS Connect in the dashboard.

 

 ```
staticx domain --site-id SITE_ID --domain app.example.com

# Later, check progress:
staticx domain-status --site-id SITE_ID
```

  Expected command flow

## How the CLI should behave.

 

1. **Install the package.** `npm install -g staticx`.
2. **Log in with a token.** `staticx login --base-url ... --token ...` stores the base URL, verifies the token, and prints the active scope plus next commands.
3. **Open the terminal guide.** `staticx guide` explains the supported commands without leaving the shell.
4. **Verify access.** `staticx whoami` calls `GET /user` and returns the current token metadata.
5. **Create or deploy.** Use the scope-specific commands shown above.
6. **Choose history mode intentionally.** Default deploys create rollback-ready versions. Add `--versioning off` only when the site should keep one baseline release for analytics and forms without growing history.
7. **Connect a domain when needed.** Use `staticx domain --site-id ... --domain ...`, then create the one DNS record shown in the terminal.
8. **Use DNS Connect only after browser approval.** The CLI cannot grant external DNS-provider access silently; it should direct the user to the dashboard when they want StaticX to create DNS automatically.
9. **Inspect logs after changes.** Use `staticx logs --site-id ...` when a deploy or upload needs verification.
10. **Respect plan limits.** Free allows 1 site, 500 MB storage, 500 MB uploads, 1,000 form entries, 1 team seat, and 5 rollback versions. Plus and Pro raise capacity; Unlimited uses custom capacity.
11. **Stop on quota errors.** If the CLI receives `PLAN_QUOTA_EXCEEDED`, return the exact message and clean up or upgrade before retrying.
 
  API contract

## Keep the CLI on the same route set as every other integration.

 

 | Command | Routes | Purpose |
|---|---|---|
| `staticx guide` | Local helper | Explain login, browsing, creation, deploy, logs, token scopes, and required build files. |
| `staticx whoami` | `GET /user` | Verify the token and return scope metadata. |
| `staticx workspaces` | `GET /workspaces` | List visible workspaces for a Global token. |
| `staticx sites --workspace-id ...` | `GET /projects?workspace_id=...` | List sites inside one workspace. |
| `staticx create --workspace-id ...` | `POST /projects` | Create a new site, optionally inside a workspace. |
| `staticx deploy --site-id ... --dir dist` | `POST /projects/{project}/files`, `GET /projects/{project}/imports/status`, `POST /projects/{project}/deployments` | Queue the build ZIP, wait for import completion, then publish it. Use `--versioning off` for a single baseline release. |
| `staticx domain --site-id ... --domain ...` | `POST /projects/{project}/domain` | Start manual custom domain setup and print the DNS record to create. |
| `staticx domain-status --site-id ...` | `GET /projects/{project}/domain` | Check DNS, SSL, and activation status. |
| `staticx logs --site-id ...` | `GET /projects/{project}/logs` | Read project activity after deploys and uploads. |

  Strong defaults

## Keep the CLI safe by default.

 

- Prefer a Site token for deploy jobs that only touch one site.
- Use a Workspace token only when the same runner truly needs multiple sites inside one workspace.
- Reserve Global tokens for internal operator workflows, never routine release jobs.
- Keep token expiry short whenever the CLI job is temporary.
- Do not print tokens in logs, commits, screenshots, or support messages.
- Never bypass plan capacity by changing endpoints or upload modes.

[View on staticx.site](https://staticx.site/documentation/cli)