# The emit CLI

The `emit` command ships in the `@mzedstudio/emits-cli` package. Run it
installed (`npm i -g @mzedstudio/emits-cli`) or on demand
(`npx -y @mzedstudio/emits-cli <verb>`). Most verbs accept two shared flags:
`--endpoint <url>` to point at a different API origin (honored only with
`EMITS_ALLOW_CUSTOM_ENDPOINT=1` set; see [the agent API](/docs/api)), and
`--json` for machine-readable output.

Your credentials and active account live in the machine-global `~/.emits/`
home, which is why every verb works from any directory. (A pre-rename
`~/.shortwind/` home is migrated automatically, and the pre-spinout
`@shortwind/cli` package ships these same verbs under the legacy
`shortwind cloud <verb>` namespace.)

## `emit login`

Authenticate via the OAuth device flow and store a credential in the global
home. Prints a verification URL and code to enter in a browser, then polls
until approved. Requests `pages:read` and `pages:write` by default; pass
`--scope <scope>` (repeatable) to request more, e.g. `--scope domains:bind`.

## `emit whoami`

Show the signed-in account: label, account id, scopes, and endpoint, plus any
other accounts in the home. Exits `1` when not logged in, so scripts can gate
on it. `--json` emits the same as a machine-readable object.

## `emit init-global`

Repair the global `~/.emits/` home (`login` creates it, so you rarely need
this). `--force` overwrites an existing home.

## `emit publish <file>`

Create a page from an HTML file (`POST /v1/pages`), freeze version 1, and
print the live URL, id, and version.

- `--domain <slug>`: desired subdomain/slug.
- `--tag <tag>`: attach a tag (repeatable).
- `--visibility <level>`: `public` | `unlisted` | `private`.
- `--idempotency-key <key>`: safe-retry key.
- `--bundle`: publish `<file>`'s whole directory as a linked multi-page unit,
  with `<file>` as the entry point. See
  [multi-page publishes](/docs/publishing#multi-page-publishes).

On a slug collision it prints the existing page id and the `update` command to
reuse it.

## `emit update <id> <file>`

Republish HTML to the same URL as a new version (`PATCH /v1/pages/{id}`).
Accepts `--idempotency-key <key>`.

## `emit find`

Locate existing pages (`GET /v1/pages`). Prints a table of id, slug, version,
visibility, and tags, or `no pages found`.

- `--q <query>`: free-text query.
- `--tag <tag>`: filter by tag (repeatable; matches pages carrying all of
  them).

## `emit get <id>`

Fetch page metadata and the full version list (`GET /v1/pages/{id}`).

## `emit delete <id>`

Tombstone a page so it stops resolving (`DELETE /v1/pages/{id}`). Prompts for
confirmation unless you pass `-y` / `--yes`.

## `emit visibility <id> <level>`

Set a page's visibility to `public`, `unlisted`, or `private` without
republishing (`PATCH /v1/pages/{id}/visibility`).

## `emit bind-domain <hostname>`

Bind an account-level custom domain (`POST /v1/domains`). Requires the
`domains:bind` scope; if your credential lacks it, the CLI re-runs login to
step up for this one operation. See [custom domains](/docs/domains).

## `emit domains`

List the account's custom domains and their status (`GET /v1/domains`).

## `emit approve-domain <hostname>`

Approve a domain sitting at `pending-human` (`POST /v1/domains/approve`).

## `emit skill`

Print the Emits `SKILL.md`, the document that teaches a coding agent when to
reach for Emits and which verbs exist. Writes to stdout, or to a file with
`--out <file>` (its `references/` land alongside). The same renderer produces
[the Agent Plugin](/docs/agent-plugin)'s skill, so the two cannot disagree.

## `emit mcp`

Run the Emits MCP server on stdio, for agent clients that launch tools as
subprocesses. Prints nothing on success: stdout is the JSON-RPC channel. See
[MCP](/docs/mcp).