@naturali/cli 0.1.0

package/README.md

@@ -0,0 +1,107 @@
+# @naturali/cli
+
+The `naturali` command — one command per [naturali.ai](https://naturali.ai) API
+operation, generated from the [OpenAPI specs](../../api/openapi/).
+
+```bash
+pnpm add -g @naturali/cli
+naturali configure
+```
+
+## Configuration
+
+`naturali configure` saves a profile to `~/.naturali/config.json`: the API base
+URL, a token (`nat_sk_…` or a session JWT), and an optional default project.
+
+Environment variables take precedence, which is what CI should use:
+
+| Variable | Purpose |
+| --- | --- |
+| `NATURALI_BASE_URL` | API origin (e.g. `https://api.naturali.ai`). Overrides a profile's stored URL. |
+| `NATURALI_TOKEN` | Bearer credential. With `NATURALI_BASE_URL` set, no profile is needed. |
+| `NATURALI_PROJECT` | Default `project_id`, so project-scoped commands can omit `--project-id`. |
+| `NATURALI_PROFILE` | Profile to use when `--profile` is not passed. Defaults to `default`. |
+
+Use `--profile <name>` to switch profiles per command.
+
+## Commands
+
+Every operation is a command named by kebab-casing its `operationId`:
+`createAgent` → `create-agent`, `rotateApiKey` → `rotate-api-key`.
+
+```bash
+naturali list-commands              # every command, with its description
+naturali create-agent --help        # one command's flags, and its docs link
+```
+
+Flags are the spec's parameter names. Kebab-case is the documented convention,
+but snake_case and camelCase are accepted too — `--project-id`, `--project_id`
+and `--projectId` are the same flag.
+
+```bash
+naturali list-agents --project-id proj_V1StGXR8Z5jdHi6B --limit 10
+
+naturali create-agent \
+  --project-id proj_V1StGXR8Z5jdHi6B \
+  --provider-id aip_V1StGXR8Z5jdHi6B \
+  --name support-triage \
+  --tool-ids tool_V1StGXR8Z5jdHi6B
+```
+
+Where a flag's value goes — URL path, query string or request body — comes from
+the spec, so you never have to know.
+
+### Values
+
+| Kind | How to pass it |
+| --- | --- |
+| String | `--name support-triage` |
+| Number / boolean | `--temperature 0.7`, `--force` (a bare flag is `true`) |
+| Object | `--tool-choice '{"type":"tool","name":"get_weather"}'` |
+| Array | repeat the flag (`--tool-ids a --tool-ids b`) or pass a JSON array (`--tool-ids '["a","b"]'`) |
+
+An array-typed field is always sent as a list, even with one value.
+
+### Shorthands for path parameters
+
+With a default project configured, `--project-id` can be omitted:
+
+```bash
+export NATURALI_PROJECT=proj_V1StGXR8Z5jdHi6B
+
+naturali list-agents
+naturali get-agent agent_V1StGXR8Z5jdHi6B   # positional fills the last path param
+naturali get-agent --id agent_V1StGXR8Z5jdHi6B
+```
+
+A positional argument or `--id` fills the **one** path parameter still missing;
+when more than one is unresolved the command fails and names them rather than
+guessing.
+
+## Output
+
+The response body is printed to stdout as formatted JSON, so it pipes into `jq`:
+
+```bash
+naturali list-agents | jq -r '.data[].id'
+```
+
+A non-2xx response prints the platform's error envelope to **stderr** and exits
+`1`:
+
+```json
+{
+  "status": 403,
+  "error": { "code": "access_denied", "message": "Not your project" }
+}
+```
+
+## Generation
+
+`src/generated/routes.ts` is build output — never edit it, and never commit it.
+It is rebuilt from `api/openapi/v1/*.yaml` by `pnpm generate`, which `typecheck`,
+`test` and `build` all run first. See [`../README.md`](../README.md) for the
+pipeline.
+
+Hand-written source is limited to dispatch, flag parsing, credentials and help;
+there is no per-endpoint code.

package/bin/naturali

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import('../dist/index.mjs').then(({ runCli }) => {
+  return runCli(process.argv);
+});