@naturali/cli

The naturali command — one command per naturali.ai API operation, generated from the OpenAPI specs.

pnpm add -g @naturali/cli
export NATURALI_TOKEN=nat_sk_...

Configuration

The CLI always talks to https://api.naturali.ai — the only naturali.ai API origin, and not configurable. Credentials and the default project come from the environment:

Commands

Every operation is a command named by kebab-casing its operationId: createAgent → create-agent, rotateApiKey → rotate-api-key.

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.

naturali list-agents --project-id proj_V1StGXR8Z5jdHi6B --limit 10

naturali create-agent \
  --project-id proj_V1StGXR8Z5jdHi6B \
  --provider-id aip_V1StGXR8Z5jdHi6B \
  --name support-triage \
  --tool-bindings '[{"tool_id":"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

An array-typed field is always sent as a list, even with one value.

File values

@path reads the value from disk. A .yaml, .yml or .json file is parsed, and a { "file": "..." } inside it is replaced by that file's contents, resolved relative to the document holding the reference:

# naturali/squad.formation.yaml
resources:
  Playbook:
    type: document
    properties:
      path: /squad/playbook.md
      content:
        file: ../intelligence/playbook.md

naturali validate-formation --project-id proj_V1StGXR8Z5jdHi6B \
  --template @naturali/squad.formation.yaml

That is what lets a formation template declare documents whose text is versioned beside it, instead of carrying a pasted copy of each. Any other extension is read as text and never parsed, so a markdown file opening with { stays a string.

Only a lone { "file": ... } is a reference — an object with other keys beside it is left alone, so a property genuinely named file is not hijacked.

A template can read any file you can. Read one you did not write before deploying it.

Every path parameter a command needs must be passed explicitly; a command that leaves one out fails and names it rather than guessing.

Output

The response body is printed to stdout as formatted JSON, so it pipes into jq:

naturali list-agents --project-id proj_V1StGXR8Z5jdHi6B | jq -r '.data[].id'

A non-2xx response prints the platform's error envelope to stderr and exits 1:

{
  "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 for the pipeline.

Hand-written source is limited to dispatch, flag parsing, credentials and help; there is no per-endpoint code.

Testing

pnpm test runs the unit suite against a mocked fetch — flag parsing, dispatch, and help output, on every pull request.

pnpm e2e (tests/e2e/smoke.ts) is different: it drives the built CLI binary (bin/naturali) as real subprocesses against the real, deployed API, using a NATURALI_E2E_API_KEY account-scoped key. It proves the one thing the mocked suite can't — that the CLI, the @naturali/sdk it bundles, and the live API actually agree — and it provisions and archives its own throwaway project. It costs real model-provider money, so it only runs as part of the e2e job in main.yml, never on pull requests.

Versioning

Releases are automatic, and the version is shared with the API and with @naturali/sdk — one number, one git tag, three packages. @naturali/[email protected] speaks to API 0.28.0, and naturali --help is generated from the specs that release was built from, so it is always the authority on what your version can do.

Any change to api/openapi/v1/*.yaml regenerates this package and publishes it — new endpoints become new commands without anyone editing the CLI — and so does a change to @naturali/sdk, which is bundled in at build time rather than resolved from npm.

fix:/chore: changes release a patch and feat: a minor, inferred from the squashed commit subject. Every case publishes on merge, breaking changes included. See the repository's PIPELINE.md and CHANGELOG.md.