# 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](https://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:

```bash
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

```bash
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:

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

Publish it:

```bash
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`:

```bash
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`):

```bash
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](/docs/agent-plugin), or wire up
[MCP](/docs/mcp) directly; the same publish/update loop becomes tool calls
that return URLs.

## Next

- [Publishing & versions](/docs/publishing): slugs, visibility, tags, and the
  version model in depth.
- [Custom domains](/docs/domains): serve pages on your own domain (Pro).
- [The agent API](/docs/api): drive publish and update over HTTP instead of
  the CLI.