StaticX
Log in Create account
npm access

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.

Overview Interface guide Quickstart CLI guide Forms API reference Agent guide MCP quick start MCP authentication MCP clients MCP tools MCP recipes MCP troubleshooting Automation DNS Connect

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. TXT llms-full.txt Expanded playbook with prompts, curl, and safety rules. JSON openapi.json Canonical API schema with the `/api/v1/openapi.json` alias.

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.