agentpub.io

The official CLI for agentpub.io — agent-native publishing. Turn a directory of HTML/CSS/JS into a live URL in one command. No build step, no config, zero runtime dependencies.

# Publish a folder — anonymous 24h site, no account needed
npx agentpub.io publish ./dist

# Sign in (device pairing, approve in your browser), then publish owned sites
npx agentpub.io login
npx agentpub.io publish ./dist --name my-site

What it is

agentpub uploads a static site directory to agentpub and prints its live URL. Run it anonymously for a throwaway 24-hour site, or login once to publish permanent sites you own. It talks to the same HTTP API the hosted MCP server and web app use.

Install

Run on demand with npx agentpub.io <command>, or install globally:

npm install -g agentpub.io
agentpub --help

Requires Node.js >= 18 (uses native fetch).

Commands

Command	What it does
agentpub login	Device pairing: prints an approval URL + code, waits for you to approve in a browser, then stores your key.
agentpub logout	Removes the stored key.
agentpub publish <dir>	Publishes a directory. Owned when signed in, anonymous otherwise.
agentpub list	Lists your owned sites (slug, title, URL). Requires a key.
agentpub open <slug>	Prints a site's live URL and tries to open it.
agentpub mcp	Prints the ready-to-paste MCP config for the hosted server.
agentpub --help / --version	Usage / version.

publish flags

• --name <handle> — a stable, account-scoped handle. Republishing with the same name updates that site instead of creating a new one (idempotent).
• --title <text> / --description <text> — set the artifact's title/description (otherwise derived from the page's <title> / <meta name="description">).

Per-file cap is 25 MB, per-site cap is 100 MB, up to 2000 files. Dotfiles are skipped.

Auth flow

agentpub login uses device pairing — you never paste a key into a terminal or chat:

1. The CLI requests a pairing code and prints an approval URL + short code.
2. You open the URL and approve in your browser.
3. The CLI polls until the key is minted, then stores it at ~/.agentpub/config.json (mode 600).

Overrides:

• AGENTPUB_API_KEY — use this key instead of the stored one (handy for CI).
• AGENTPUB_HOST — point at a different API base (default https://agentpub.io).

Your key is only ever sent as a Bearer token or written to the 600 config file — it is never printed to stdout or logs.

MCP

Prefer using agentpub straight from your agent? Add the hosted MCP server instead of the CLI:

agentpub mcp

{
  "mcpServers": {
    "agentpub": {
      "url": "https://agentpub.io/mcp"
    }
  }
}

The client discovers OAuth automatically and issues a scoped key — no key handling required.

For agents

Every command is built to be driven by an agent: predictable JSON, typed exit codes, and no interactive blocking.

JSON output. Pass --json, or just pipe — when stdout is not a TTY the CLI auto-emits a single JSON object. Human TTY output is unchanged. The API key never appears in any output.

$ agentpub publish ./dist --json
{"ok":true,"url":"https://calm-saddle-7h2k.agentpub.io/","slug":"calm-saddle-7h2k","authenticated":false,"anonymous":true,"expiresIn":"24h","claimUrl":"https://agentpub.io/claim/tok"}

Errors are {"ok":false,"error":"<code>","message":"..."} on stdout (with a human hint on stderr); rate-limit errors add "retryAfter":<seconds>. Per-command success shapes: list → {"ok":true,"sites":[{slug,title,url}]}, open → {"ok":true,"slug,"url"}, login → {"ok":true,"signedIn":true,"keyName?,"configPath"}, logout → {"ok":true,"removed"}, mcp → {"ok":true,"endpoint","config"}.

Exit codes — branch on these instead of parsing text:

Code	Meaning
0	success
2	usage / validation error (bad args, missing dir, caps hit)
3	auth required or failed — run agentpub login
4	not found (unknown slug)
5	rate-limited (respects / echoes Retry-After)
7	server / network error

Flags. --quiet prints ONLY the primary value (publish/open → the URL, mcp → the endpoint, login → nothing); errors still go to stderr with the right exit code. --json takes precedence over --quiet. --no-input guarantees nothing ever blocks on a human: login caps its pairing poll and exits 3 instead of waiting, and any future prompt fails fast with exit 2.

url=$(agentpub publish ./dist --quiet) || exit $?

Env vars. AGENTPUB_API_KEY overrides the stored key (handy for CI); AGENTPUB_HOST points at a different API base (default https://agentpub.io).

What this CLI touches

One network target, one config file, zero surprises:

• Network: HTTPS to https://agentpub.io only (or your explicit AGENTPUB_HOST). No telemetry, no other hosts.
• Disk: reads only the directory you publish; writes only ~/.agentpub/config.json (mode 600) after login.
• Zero runtime dependencies, no install scripts. Your key never appears in any output (test-enforced).

Full details in SECURITY.md. Source: github.com/agentpub-io/cli — releases are published from CI with npm provenance.

License

MIT