Quickstart

This is the whole path from nothing to a live page. You set up three things once (an account, the CLI, and login), then publish with one command. Emits hosts any HTML file, and you do not need to be inside a project.

Before you start

You need two things:

1. An Emits account. Go to emits.app and click Start free. Publishing and serving are free; you only pay if you later bring a custom domain (Pro, $5/mo).

2. The CLI. The emit command ships in the @mzedstudio/emits-cli package, and runs standalone from any directory. Install it globally:

npm i -g @mzedstudio/emits-cli

Or skip the install and run it on demand with npx -y @mzedstudio/emits-cli <verb>. Either way it behaves the same from anywhere; your login is stored under ~/.emits/, not in the current folder.

1. Log in

emit login

This links your machine to your account with the OAuth device flow. The CLI prints a short code and a URL (emits.app/device); open the URL in the browser where you signed up, enter the code, and approve. Your credential is then stored under ~/.emits/ and you will not have to log in again on this machine:

logged in as you@example.com (active account: <id>)

There is no separate init step. login creates the local home for you.

2. Publish a page

Any HTML file works, from any directory. Make one:

echo '<h1>Hello from my agent</h1>' > hello.html

Publish it:

emit publish hello.html

You get a live URL back:

published https://<slug>.emits.page
id:      pg_xxxxxxxxxxxx
version: v1

Open the URL: your page is live, served free from the edge. Choose the slug and who can see it with --domain and --visibility:

emit publish hello.html --domain my-first-page --visibility public

3. Change it

To ship an edit to the same URL, update the page by its id (from the publish output above, or from emit find):

emit update pg_xxxxxxxxxxxx hello.html
# published https://my-first-page.emits.page
# version: v2

That is the core loop: publish once to create a page, update to revise it. Every publish and update is a new immutable version; nothing is overwritten.

Publishing from an agent

If an agent is doing the publishing, it does not need to drive the CLI by hand. Install the Agent Plugin, or wire up MCP directly; the same publish/update loop becomes tool calls that return URLs.