@host0/cli 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,73 @@
-# Temporary Holding Version
+# @host0/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Deploy and manage [host0](https://host0.ai) apps from the terminal. host0 is
+hosting for whatever your agent creates: HTML, sites, apps with a shared
+database, Markdown, PDFs — at a link you can share.
+
+```sh
+npx @host0/cli deploy ./site        # or: npm i -g @host0/cli && host0 deploy ./site
+```
+
+Node 18.18 or newer, no dependencies. With no API key, `deploy` starts a device
+login: it prints a link and a code and exits 3 — approve it in your browser,
+then run the same command again.
+
+## Commands
+
+| Command | Does |
+|---|---|
+| `host0 deploy <dir\|file>` (`publish`, or just `host0 <path>`) | Publish a folder or one file; prints the live URL. `--name --slug --app-id --visibility private\|link\|public --message --no-login --timeout <s>` |
+| `host0 login [--wait] [--timeout <s>]` | Start (or re-show) a device login, exit 3; `--wait` waits for the approval and saves the key |
+| `host0 logout` | Revoke the stored key and delete `~/.host0/credentials` |
+| `host0 whoami` | Account email and plan |
+| `host0 ls` | Your apps |
+| `host0 inspect <app>` | URL, access, live version, shares |
+| `host0 pull <app> [dir]` | Download the live files into a new folder; deploying it publishes the next version |
+| `host0 versions <app>` | Versions, the live one marked |
+| `host0 rollback <app> <version>` (`restore`) | Put an earlier version live again, as a new version |
+| `host0 visibility <app> <private\|link\|public>` | Change who can open it |
+| `host0 rename <app> [--slug s] [--name n]` | Rename the URL and/or display name |
+| `host0 share <app> <email…>` / `host0 unshare <app> <email>` | Invite / remove people |
+| `host0 rm <app> --yes` | Delete an app |
+| `host0 analytics <app> [--period 24h\|7d\|30d\|90d\|365d]` | Visitors and page views |
+| `host0 records <app> [collection] [--export]` | Shared data: collections, records, or the full JSON export |
+| `host0 api <path> [-X METHOD] [-d json]` | Authenticated request to `/api/v1/…` on the base URL |
+
+`<app>` is a slug or an app id. Global flags: `--json` (the API's JSON body,
+unchanged, for the control commands), `--api-key`, `--base-url`,
+`--allow-nonhost0-base-url`, `--client`, `--help`, `--version`.
+
+## Output contract
+
+- **stdout** carries only the result: `deploy` prints the live URL, `pull` the
+  folder, control commands their answer (or the raw JSON with `--json`).
+- **stderr** carries progress, warnings and `key=value` lines for agents:
+  `publish_result.*` (deploy), `pull_result.*` (pull), `login_result.*`
+  (device login). On an API error: `  - <problem>` lines,
+  `publish_result.error=<code>`, `publish_result.upgrade_url=…` when a plan
+  limit applies, then `error: <context>: <message>`.
+- **Exit codes:** `0` ok · `1` error · `3` waiting for the user to approve a
+  sign-in · `130`/`143` interrupted (an app this run created but never put
+  live is deleted first).
+
+## Compatible with publish.sh
+
+The CLI is the Node counterpart of the host0 skill's `publish.sh`, and an
+agent can switch between them mid-project: same credentials file
+(`~/.host0/credentials`, `$HOST0_API_KEY`, `--api-key`), same pending device
+login (`~/.host0/device.json`), same per-folder `.host0/state.json`, same file
+walk and content types, same stdout/stderr lines and exit codes. It sends
+`x-host0-client: <agent>/cli-<version>` (publish.sh sends
+`<agent>/<script version>`), only to the platform API — never to signed upload
+or download URLs.
+
+`HOST0_HOME` replaces `~/.host0` (tests use it so the real credentials are
+never touched).
+
+## Develop
+
+```sh
+npm install
+npm run typecheck
+npm test          # builds dist/host0.mjs, then node --test
+```