@claypi/cli 0.0.1

package/README.md

@@ -0,0 +1,70 @@
+# `@claypi/cli`
+
+> The Clay command-line interface — the `clay` binary.
+
+JSON-first, agent-first. Every command emits structured JSON on stdout for success and a typed error envelope on stderr; there is no human-formatted output mode. End-user-facing docs live in `clay --help` and `clay <command> --help`. The authoring guide for new commands is [`AGENTS.md`](./AGENTS.md).
+
+## Local Development
+
+This package lives under `apps/cli/` in the `clay-base` monorepo. Top-level setup (`yarn install`, etc.) is covered in the repo's root `AGENTS.md`.
+
+### Build, test, lint
+
+```bash
+yarn workspace @claypi/cli build         # bundle the binary into dist/
+yarn workspace @claypi/cli dev           # tsup --watch (rebuilds on save)
+yarn workspace @claypi/cli tsc           # type-check
+yarn workspace @claypi/cli lint
+yarn workspace @claypi/cli format:check
+yarn workspace @claypi/cli test          # unit + e2e (e2e requires `build` first)
+```
+
+### Running the locally built CLI
+
+After `build`, the entry point is `dist/index.js`. Invoke it directly with `node`:
+
+```bash
+# From this package (apps/cli):
+node dist/index.js --help
+node dist/index.js whoami
+node dist/index.js tools list --limit 5
+```
+
+Point at a non-prod backend with `CLAY_BASE_URL`, and isolate your config so it doesn't clobber your real `~/.config/clay/`:
+
+```bash
+# Talk to local API + use a throwaway config dir
+CLAY_BASE_URL=http://localhost:3001 \
+CLAY_CONFIG_HOME=/tmp/clay-dev \
+  node dist/index.js login --stdin <<< "$LOCAL_API_KEY"
+
+CLAY_BASE_URL=http://localhost:3001 \
+CLAY_CONFIG_HOME=/tmp/clay-dev \
+  node dist/index.js whoami
+```
+
+`CLAY_CONFIG_HOME` makes the CLI write to `<that-dir>/clay/config.json` instead of `~/.config/clay/config.json`, so you can keep prod and dev credentials separate.
+
+If you want to use the iteration loop with `dev`/watch mode, run `dev` in one terminal and invoke `node dist/index.js ...` in another — each run reads the freshly rebuilt bundle.
+
+### Optional: link the binary as `clay`
+
+If you want the literal `clay` command in your shell pointing at your local build:
+
+```bash
+# From apps/cli/
+yarn build
+npm link              # registers `clay` -> dist/index.js
+clay whoami
+npm unlink -g @claypi/cli   # when you're done
+```
+
+(Use sparingly — it shadows any globally installed `@claypi/cli`.)
+
+### E2E tests
+
+The e2e tests spawn the built binary against a mock server (`tests/e2e/helpers/mock-api.ts`); they skip themselves with a console warning if `dist/` is missing, so run `build` first.
+
+---
+
+For everything else — output contract, error model, exit-code categories, command-authoring conventions, progressive disclosure, and the evolution rules — see [`AGENTS.md`](./AGENTS.md).