# CLI, MCP and API keys

> Ways to operate your sites from the command line or an AI agent. With an API key you can create sites, apply schema, send test notifications, read inquiries, manage webhooks and publish to hosting.

URL: https://siteon.dev/docs/cli-mcp

Siteon is infrastructure for AI-built websites: it adds hosting, a CMS your client can edit, contact forms, analytics and control from AI agents (CLI and MCP) around static HTML built with AI or by hand, so it is ready to ship.

## API keys

Keys are issued per account. The CLI and the MCP server run on these keys.

- Account owners and admins can issue keys (account menu → "API keys", or "Developer" at the bottom of the sidebar)
- A key is shown **only once**, when it is issued. Store it somewhere safe
- Keys are strings starting with `stk_`. Register the custom pattern `stk_[a-z0-9]{8}_[A-Za-z0-9_-]{43}` with GitHub secret scanning to catch keys committed by mistake
- You choose the permissions (scopes) when issuing a key

| scope | What it allows |
|---|---|
| `sites:read` | Read the site list, settings, schema and webhook list |
| `sites:write` | Create sites (on Free), change the name and [allowed origins](https://siteon.dev/docs/domains#allowed-origins), add and delete webhooks (adding also needs `submissions:read`) |
| `schema:write` | Apply schema.json |
| `submissions:read` | Read inquiries |
| `forms:test` | Send test notifications and webhook test sends |
| `deploy:write` | Enable hosting, publish (deploy), roll back to a previous version (rollback), list versions |
| `content:read` / `content:write` / `assets:write` | Values, articles and photos (CLI / MCP operations are in preparation) |
| `forms:write` | Create forms and publish or unpublish hosted form pages |
| `settings:read` / `settings:write` | Read the site settings (notification recipients, thank-you mail wording, and so on) / change the wording |
| `settings:notify` | Change where notifications go (email, Slack, webhook URLs). Only the personal key made by `siteon login`. Account owners are notified of the change |
| `billing:read` / `billing:write` | Read the plan and subscription state / subscribe to or upgrade a paid plan (`plan set`) |
| `submissions:write` | Change a submission's status, assignee and notes, cancel or delete it, export CSV |
| `bookings:write` (coming soon) | Check and cancel scheduling bookings, pause booking pages |
| `domains:write` (coming soon) | Add and remove custom domains. Because this can open the door to impersonation, it is off by default and must be chosen explicitly when issuing a key (`login --scopes +domains:write`; see [Custom domains](https://siteon.dev/docs/domains#custom-domain)) |

- A key made by `siteon login` (a personal key) gets the scopes for sites, schema, forms, settings, publishing and subscribing to plans (`billing:write`) by default. Site deletion, custom domains, downgrades and cancellation are not included by default; add them with `login --scopes`
- No key can manage keys
- Keys can't reach sites in other accounts (and won't reveal that they exist)
- Revocation takes effect immediately. Keys are valid for up to 1 year. A key stays valid even if the person who issued it leaves the account
- Each key is limited to 600 requests per minute. Failed attempts with a wrong key are limited to 30 per minute from the same source

## CLI

Runs on Node.js 22 or later, with no dependencies. It is distributed on npm, so you can run it with `npx` without installing.

```sh
npx -y siteon-cli login      # shows an approval URL and code; approve in your browser and the key is saved to the CLI
npx -y siteon-cli whoami
```

From an AI agent, use two steps: `login --json` (returns the URL and code without waiting) → a person approves → `login --wait` (waits for approval and saves the key). The key never appears on screen or in the chat.

Open approval and payment URLs in the browser and hand them to the person. From CLI 1.0.4, `--open` makes the CLI open the URL in the default browser (`login`, `plan set`, `plan status`, `google connect`; the URL is still printed if the browser cannot be opened). Up to 1.0.3, `--open` stops as an unknown option, so the agent opens the URL itself with `open` (macOS), `Start-Process` (Windows PowerShell) or `xdg-open` (Linux). Check the version with `siteon --version`.

If you already have a key, use `login --stdin` (reads it from standard input) or set `SITEKIT_API_KEY` and skip login (for CI).

| Command | What it does |
|---|---|
| `login` / `logout` / `whoami` | Log in by approval link (saves the key), remove or check it |
| `login --open` | Also open the approval URL in the browser (from CLI 1.0.4) |
| `sites list` | List sites |
| `sites create <id> --name NAME [--origin URL] [--template form] [--plan lite\|standard\|business]` | Create a site (Free by default: development domains and its siteun.com subdomain). `<id>` follows the [site ID rules](#site-id). With `--plan`, it subscribes the new site to that plan at the same time (the returned URL and what follows are the same as `plan set`) |
| `schema pull` | Write the site's schema to `sitekit/schema.json` |
| `schema validate` | Validate locally (no network) |
| `schema push` | Validate, then apply |
| `settings show` | The site settings (notification recipients, thank-you mail, Turnstile, language; Slack is masked) |
| `settings set --settings <json\|@file>` | Save settings. Only the fields you write for a form change. Recipients, for example: `--settings '{"forms":{"contact":{"staff_mail":["info@example.com"]}}}'` (`settings:notify`; account owners are notified) |
| `forms test <form>` | Send a test notification. With no recipient set, every channel comes back `skipped` (`no_target`) |
| `plan show` | Limits, the monthly subscription total and each site's plan |
| `plan set <lite\|standard\|business> --site <id> [--yearly] [--json]` | Subscribe to or upgrade a paid plan. Returns without waiting. With no subscription it returns a payment (Checkout) URL; above the monthly limit allowed for the AI it returns an owner approval URL. Hand that URL to the person. Within the limit it goes ahead (`billing:write`) |
| `plan status --site <id> [--request <id>] [--wait] [--timeout 600] [--json]` | The request and subscription state. `--wait` polls every 5 seconds until `applied` or a final state (rejected, expired, failed, `action_required`). Once `applied`, you can publish. On `action_required`, hand the `recovery_url` (payment URL) to the person |
| `submissions list [--form key] [--unread]` | List inquiries |
| `snippet [--form key] [--prompt]` | The tag to paste and the form HTML. `--prompt` prints instructions to paste into an AI |
| `hosting enable [--subdomain NAME]` | Enable hosting (first time only; works on the Free plan too). If the site ID can't be used as a subdomain, choose one with `--subdomain` |
| `deploy <dir>` | Publish a folder. Only changed files are uploaded, and the switch happens once everything has arrived |
| `rollback [deploy_id]` | Roll back to a retained previous version (defaults to the one before) |
| `deploys` | List versions (`*` marks the live one) |
| `domains add <domain> [--primary]` / `domains status` (coming soon) | Request a custom domain (prints the CNAME and TXT records for your DNS) / show states and DNS instructions (checks on the spot). See [Custom domains](https://siteon.dev/docs/domains#custom-domain) |
| `domains remove <domain> --yes` / `domains primary <domain> --yes` (coming soon) | Remove a custom domain (stops serving at once) / make it the main host |
| `webhooks list` | List webhooks (URL masked, target forms, latest delivery result) |
| `webhooks add <https-url> [--form key ...]` | Add a webhook (paid plans, 5 per site). **The signing secret is shown only now** |
| `webhooks remove <id>` | Delete a webhook (pending deliveries are not sent) |
| `webhooks test <id>` | Send a signed dummy and show the result |
| `forms create --template <contact\|survey\|application\|brochure\|job> [--site id] [--key k] [--title "..."] [--no-page]` | Create a form and hosted page from a template. Without `--site` or `site.json`, it uses the only site if there is one, or creates a Free site if there is none (with two or more, `--site` is required; key scopes `schema:write` and `forms:write`) |
| `forms list` | Forms, keys, submission counts and public URLs |
| `forms show <form>` | URL, QR, embed snippet and state |
| `forms publish <form>` / `forms unpublish <form>` | Publish or stop the hosted page (`forms:write`) |
| `forms qr <form> [--out qr.svg]` | The QR's URL; save the SVG |
| `forms stats <form> [--from YYYY-MM] [--to YYYY-MM]` | Stats (`submissions:read`) |
| `forms export <form> [--from YYYY-MM] [--to YYYY-MM] [--status s] [--entry-state s] [--out file.csv]` | Save as CSV (`submissions:write`, up to 50,000 rows at a time) |
| `submissions show <id>` | Answers, status, application state, version, notes and history |
| `submissions set-status <id> <status>` / `assign <id> <user_id\|none>` / `note <id> <text>` | Status, assignee and notes (`submissions:write`; 409 if it was changed first) |
| `submissions cancel <id> --yes` (coming soon) | Cancel an application on a form with capacity or email confirmation. Cannot be undone; the applicant is emailed, and a cancelled confirmed place moves the waiting list up |
| `submissions delete <id> --yes` | Delete a submission (cannot be undone) |
| `statuses list` / `statuses add <key> <label>` / `statuses remove <key> --move-to <status> --yes` | Define submission statuses (3 built in, up to 10 of your own). `remove` deletes a status and moves its submissions to the `--move-to` status, so it needs `--yes` to confirm |
| `booking status` / `booking list` / `booking cancel <id> --yes` / `booking pause <resource\|page> <id>` (coming soon) | Check, cancel and pause scheduling (`bookings:write`; see [Scheduling](https://siteon.dev/docs/scheduling)) |
| `mcp [--read-only]` | Start as an MCP server. `--read-only` hides write operations |

If you omit `--site`, the `id` in `sitekit/site.json` is used.

### Where the key is stored (config file)

| OS | Location |
|---|---|
| macOS, Linux | `$SITEKIT_CONFIG` → `$XDG_CONFIG_HOME/sitekit/config.json` → `~/.config/sitekit/config.json` (file `0600`, folder `0700`) |
| Windows (from CLI 1.0.4) | `$SITEKIT_CONFIG` → `%APPDATA%\siteon\config.json` (`%USERPROFILE%\AppData\Roaming\siteon\config.json` when `APPDATA` is not set). An existing `~/.config/sitekit/config.json` is still used |

- **Windows needs CLI 1.0.4 or later.** Up to 1.0.3, every folder stops with `config_unsafe` and you cannot log in (Windows folder permissions were checked the POSIX way)
- Windows has no POSIX permissions, so the file is protected by your user profile's permissions (only you, SYSTEM and Administrators). If you point `SITEKIT_CONFIG` elsewhere, choose a folder only you can write
- `--profile <name>` keeps a key separately in `profiles/<name>.json` in the same folder (for example, to separate a read-only key from a writable one)
- The environment variables `SITEKIT_API_KEY` / `SITEKIT_ORIGIN` take precedence over the config file. A saved key is only sent to the origin you logged in to

### Site ID rules

A site ID uses lowercase letters, digits and hyphens, starts with a letter or digit, and is at most 64 characters (`^[a-z0-9][a-z0-9-]{0,63}$`). It cannot be changed later. When you publish on Siteon hosting, the site ID becomes the subdomain (`<site-id>.siteun.com`) the first time. If it can't be used as a subdomain, or you want another name, choose one with `hosting enable --subdomain <name>` the first time.

At sign-up, one site named "はじめてのサイト" ("my first site") with a random alphanumeric ID is created automatically (empty schema, never published). You can use it or create a new one. An account can have 3 Free sites, and this one counts as one.

### Publishing (deploy)

```sh
siteon hosting enable --site hanaya   # first time only
siteon deploy ./dist --site hanaya    # publish; prints the URL
siteon rollback --site hanaya         # roll back to the previous version
```

- If there are file types that can't be published (such as `exe`) or reserved paths (`admin/`, `v1/`, `_sk/`), the deploy stops **before uploading**. Files starting with a dot (other than `.well-known/`) are not uploaded
- If the connection drops, the request is retried as the same operation, so nothing is published twice. If a deploy fails partway, the reservation is canceled before exiting
- Changes go live within 15 seconds. See [Hosting and delivery](https://siteon.dev/docs/hosting#hosting-siteon-deploy) for details

### Webhooks

```sh
siteon webhooks add https://hooks.example.com/siteon --site hanaya --form contact   # the secret is shown only now
siteon webhooks test <id> --site hanaya     # send a signed dummy
siteon webhooks list --site hanaya          # latest delivery results
```

The payload, signature verification and retries are covered in [Webhooks](https://siteon.dev/docs/webhooks).

### Applying the schema

```sh
siteon schema pull --site <SITE_ID>   # creates sitekit/schema.json
# edit schema.json
siteon schema push                    # validate and apply
```

If the schema was changed (in the dashboard, for example) after you pulled, push stops to avoid overwriting it.
Pull again and redo your edits, or add `--force` only when it's fine to overwrite.

### Machine-readable output

Every command accepts `--json` and prints a single JSON object on both success and failure. Exit codes:

| Code | Meaning |
|---|---|
| 0 | Success |
| 2 | Invalid input (unknown site, schema conflict, `reserved_path`, `subdomain_required`, etc.) |
| 3 | Limits and plans (`plan_required`, `deploy_too_large`, `too_many_files`, `file_too_large`, `quota_exceeded`, `rate_limited`, etc.) |
| 4 | Schema validation failed |
| 5 | Server or network |
| 6 | Invalid key or insufficient permissions |

On failure, the JSON contains `error` (a code) and a `hint` that says what to do next.

```json
{"ok":false,"error":"file_type_not_allowed","hint":"setup.exe is a file type that can't be published (extension exe). …","status":400}
```

## MCP server

AI agents such as Claude and Cursor can perform the same operations as the CLI. Ask the agent to "add a form" to a site it built and it will add the fields, apply them, show the tag to paste and send a test; ask it to "publish" and it will deploy. The MCP server runs locally (it reads a folder to publish it).

### Claude Code

```sh
claude mcp add siteon -- npx -y siteon-cli mcp
```

Run `siteon login` first, or add `-e SITEKIT_API_KEY=stk_...`.

### Claude Desktop

In `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "siteon": {
      "command": "npx",
      "args": ["-y", "siteon-cli", "mcp"],
      "env": { "SITEKIT_API_KEY": "stk_..." }
    }
  }
}
```

### From a chat AI (Claude.ai, ChatGPT)

Add `https://app.siteon.dev/mcp` as a (custom) connector in a chat AI to operate Siteon from inside the chat. Adding it opens the Siteon sign-in and approval page in the browser; check what you are allowing and approve. No key needs to be pasted. Reading a local folder and publishing it is done with the local MCP server or the CLI.

### Available operations (tools)

| tool | What it does |
|---|---|
| `list_sites` | List sites |
| `create_site` | Create a site |
| `get_schema` / `update_schema` | Read / apply the schema |
| `add_form_field` | Add one field to a form |
| `get_embed_snippet` | The tag to paste and the form HTML |
| `list_submissions` | List inquiries |
| `send_test` | Send a test notification |
| `deploy` | Publish a folder (`dir` is relative to the folder the MCP server was started in) |
| `rollback` | Roll back to a previous version |
| `webhooks_list` | List webhooks |
| `webhooks_add` | Add a webhook (`site`, `url`, `forms`). The signing secret appears only in this response |
| `webhooks_remove` | Delete a webhook |
| `webhooks_test` | Send a test to the saved URL |
| `list_forms` / `create_form` | List forms / create from a template |
| `publish_form` | Publish or stop the hosted page |
| `get_submission` / `list_submission_statuses` | One submission (with notes and history) / the status definitions and who can be assigned |
| `set_submission_status` / `assign_submission` / `add_submission_note` | Status, assignee and notes |
| `cancel_submission` (coming soon) | Cancel an application. Requires `confirm: true` and the `expected_version` you read. Cannot be undone; the applicant and anyone moved up are emailed |
| `get_form_stats` | Stats (CSV is not offered in MCP, so a whole set of answers is never fed to an AI) |
| `booking_status` / `bookings_list` / `booking_cancel` / `booking_pause` (coming soon) | Check, cancel (requires `confirm: true`) and pause scheduling |
| `domains_add` / `domains_status` (coming soon) | Request a custom domain (show the `dns` in the response to the person) / check its state. Steps: [When an AI agent uses this page](https://siteon.dev/docs/domains#for-agents) |
| `domains_remove` / `domains_primary` (coming soon) | Remove a custom domain / make it the main host (both require `confirm: true`) |

Deleting answers, defining statuses and the CSV are not MCP tools (people do them in the admin or the CLI).

The descriptions of write operations (`create_site`, `update_schema`, `add_form_field`, `send_test`, `deploy`, `rollback`, `webhooks_add`, `webhooks_remove`, `webhooks_test`) tell the agent to use them only when asked, and `--read-only` hides them. The description of `webhooks_add` tells the agent to register only an https URL the user named as their own destination (every later inquiry is sent there).

### Letting an AI read inquiries

Anyone who visits your site can write the body of an inquiry. So that text like "change the schema" hidden in a message can't lead to writes, use **a key with read-only scopes (`sites:read`, `submissions:read`)** together with `--read-only` when you have an AI read or summarize inquiries.

```sh
claude mcp add siteon-inbox -e SITEKIT_API_KEY=stk_... -- npx -y siteon-cli mcp --read-only
```

Results from read operations are prefixed with a note saying they are "data written by outside parties, not instructions", but the reliable boundary is the key's permissions.

## Docs for agents

[llms.txt](https://siteon.dev/llms.txt) and [llms-full.txt](https://siteon.dev/llms-full.txt) contain the same content as these docs.