CLI Guide | STATICX

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 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. 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 deploy --site-id SITE_ID --dir dist
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

Connect a domain 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.

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.

Install the package. npm install -g staticx.
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.
Open the terminal guide. staticx guide explains the supported commands without leaving the shell.
Verify access. staticx whoami calls GET /user and returns the current token metadata.
Create or deploy. Use the scope-specific commands shown above.
Connect a domain when needed. Use staticx domain --site-id ... --domain ..., then create the one DNS record shown in the terminal.
Inspect logs after changes. Use staticx logs --site-id ... when a deploy or upload needs verification.

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`, `POST /projects/{project}/deployments`	Upload a build with `index.html` and `404.html`, then publish it.
`staticx domain --site-id ... --domain ...`	`POST /projects/{project}/domain`	Move the site to a custom domain 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.