@neopress/cli 3.3.0 → 4.1.0

package/README.md

@@ -0,0 +1,109 @@
+# @neopress/cli
+
+Manage your [Neopress](https://app.neopress.ai) site from the terminal — pages,
+collections, entries, forms, assets, redirects, analytics, and publishing.
+
+Designed to be driven by humans **and** by AI agents (Claude Code, Codex, etc.):
+every command speaks JSON, and `neopress guide` prints the entire command
+surface in one call.
+
+## Install
+
+```bash
+npm i -g @neopress/cli
+neopress --version
+```
+
+Or run without installing:
+
+```bash
+npx @neopress/cli guide
+```
+
+## Authenticate
+
+Log in once; the session is stored in `~/.config/neopress/tokens.json` and
+refreshed automatically.
+
+```bash
+neopress login            # OAuth in the browser
+neopress whoami           # confirm who you are
+```
+
+For CI or headless agents, skip the browser and pass a token instead:
+
+```bash
+export NEOPRESS_ACCESS_TOKEN="<token>"
+```
+
+## Quickstart
+
+```bash
+neopress sites list               # sites you can access
+neopress sites use <id|handle>    # pick the active site (persisted)
+neopress pages list               # list pages on the active site
+neopress guide                    # full command reference
+```
+
+Target a one-off site without changing the active one:
+
+```bash
+neopress --site my-blog pages list
+```
+
+## Common tasks
+
+```bash
+# Create a page from a TSX file (created as a draft)
+neopress pages create --path /about --title About --tsx ./about.tsx
+
+# Localize a page — JSON options take inline JSON or @file
+neopress pages create --path /about --i18n @i18n.json --public-locales en,ko
+
+# Create and publish a collection entry
+neopress entries create --collection 12 --data @entry.json --title Hello
+neopress entries publish <entryId>
+
+# Preview, then publish the whole site
+neopress publish preview
+neopress publish
+```
+
+Run `neopress <command> --help` for the flags and examples of any command.
+
+## JSON / AI mode
+
+Output is human-readable in a terminal and **automatically switches to JSON when
+piped or redirected**, so it composes with `jq` and tools out of the box:
+
+```bash
+neopress pages list | jq '.data[].path'
+```
+
+Force JSON in a terminal with `--json`. For agents that want the whole CLI in a
+single introspectable payload:
+
+```bash
+neopress guide --json
+```
+
+`neopress guide` is generated from the live command tree, so it never drifts from
+the installed version — treat it as the source of truth for what the CLI can do.
+
+## Configuration
+
+Resolution order for the active site: `--site` flag → `NEOPRESS_SITE_ID` →
+project config file → the site saved by `neopress sites use`.
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `NEOPRESS_ACCESS_TOKEN` | — | Auth token (skips `neopress login`) |
+| `NEOPRESS_SITE_ID` | — | Default site id (overrides the active site) |
+| `NEOPRESS_BASE_URL` | `https://app.neopress.ai` | API base URL (staging/local targets) |
+
+Per-project defaults can also live in `.neopressrc.json` (or
+`.neopress/config.json`):
+
+```json
+{ "siteId": 42, "baseUrl": "https://app.neopress.ai" }
+```