Emits

Docs

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), 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.

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.

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'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.