nominal

What this is

nominal is designed to be driven by AI agents. Top-level commands map to the tasks an agent actually performs:

• Investigate cases with hypothesis generation
• Explore cloud infrastructure — logs, metrics, dependency graphs
• Search code and wikis
• Remember findings
• Converse with the Nominal agent (streaming supported)
• Automate workflows from a catalog
• Connect integrations and cloud accounts

The full API surface is available behind nominal api call <op> as an escape hatch.

Install

Pick whichever channel fits your system. All install the same Node-based bundle and require Node 18+ (Homebrew pulls Node in as a dependency; the curl + PowerShell installers check for it).

# macOS / Linux — curl
curl -fsSL https://nominal.dev/install.sh | bash

# Windows — PowerShell
irm https://nominal.dev/install.ps1 | iex

# Homebrew (tap: coreplanelabs/nominal)
brew install coreplanelabs/nominal

# npm
npm install -g @coreplane/nominal

# Bun
bun add -g @coreplane/nominal

Requires Node.js 18+ at runtime.

Version-pin the curl / PowerShell installers with:

NOMINAL_VERSION=v0.1.0 curl -fsSL https://nominal.dev/install.sh | bash
$env:NOMINAL_VERSION='v0.1.0'; irm https://nominal.dev/install.ps1 | iex

Quick start

# 1. Authenticate (pick one)
nominal auth login                            # OAuth browser (humans at a terminal)
nominal auth login --api-key sk_xxxxx         # API key (CI / agents)
nominal auth signup --email [email protected] # bootstrap a fresh account
                                              # (returns a session token; create an
                                              # API key after step 2 for long-lived use)

# 2. Workspace
nominal workspace create --name "My Workspace"   # creates + makes default
# or: nominal workspace use <workspace-id>

# 3. Connect your stack (discover what's available first)
nominal integration catalog
nominal integration connect --type <type>        # see `nominal integration connect --help`
nominal cloud connect --provider <provider>      # see `nominal cloud connect --help`

# 4. Work
nominal cases                                    # alias for `case list`
nominal case investigate <case-id> "<prompt>"
nominal service logs <service> --since 1h --grep error
nominal thread ask "<prompt>" --stream
nominal memory save "<finding>"

Discovering commands

Run nominal --help for the resource list, nominal <resource> --help for its commands, and nominal <resource> <command> --help for flags and examples. Help is the authoritative source — it reflects the installed version, this document does not.

For the full API surface not yet exposed as first-class commands:

nominal api list                     # browse every operation
nominal api list --tag Cases         # filter by tag
nominal api describe <operation-id>  # show its shape
nominal api call <operation-id> [--body '{...}' | --body-file path]

Agent-first defaults

| Behaviour | Default | |---|---| | Output | Text tables in TTY; JSON when stdout is piped | | List projections | Narrow set of useful fields; --full dumps complete objects | | Single object reads | Full object, with a Console: … / Next: … footer surfacing _html_url and _links | | Errors | Every error ends with the exact command that fixes it (see ERRORS.md) | | Streaming | thread ask / thread continue stream via WebSocket when --stream is passed | | Non-interactive | --non-interactive fails fast on missing args instead of prompting |

Agent flags

Combine in non-interactive (agent / CI) contexts:

nominal ... --non-interactive --quiet --output json

| Flag | Purpose | |---|---| | --non-interactive | Fail fast on missing args instead of prompting | | --quiet | Suppress spinners / progress; stdout stays pure data | | --output json | Force JSON regardless of TTY state | | --full | Disable narrow projection on list commands | | --no-wait | Return immediately (send-and-forget) | | --stream | Stream assistant tokens | | --dry-run | Show the request that would be sent without executing | | --verbose | Log HTTP method / URL / response status | | --yes | Skip destructive-action confirmations |

Environment variables

| Variable | Purpose | |---|---| | NOMINAL_API_DOMAIN | API hostname (no protocol) | | NOMINAL_API_KEY | API key | | NOMINAL_WORKSPACE_ID | Default workspace | | NOMINAL_OUTPUT | text or json (overrides TTY auto-detect) | | NOMINAL_TIMEOUT | Request timeout (seconds) | | NOMINAL_VERBOSE | Enable verbose HTTP logging | | NOMINAL_TELEMETRY | 0 / false / off disables anonymous usage telemetry | | NOMINAL_TELEMETRY_ENDPOINT | Override the telemetry endpoint (defaults to <api>/v1/telemetry/cli) | | DO_NOT_TRACK | Universal 1 disables telemetry (standard) | | NOMINAL_OAUTH_CLIENT_ID / NOMINAL_OAUTH_CLIENT_SECRET | OAuth client override (normally baked at build) | | NOMINAL_CONSOLE_DOMAIN | Consent-UI host override (defaults to the API host with api. → console.) | | NO_COLOR | Disable ANSI colours |

Configuration file

~/.nominal/config.json (mode 0600):

{
  "domain": "...",
  "workspace_id": "ws_xxxxx...",
  "api_key": "sk_xxxxx...",
  "output": "text",
  "timeout": 300
}

Precedence: CLI flags > env vars > config file > defaults.

Manage with nominal config show and nominal config set --key <key> --value <value>.

Authentication

| Command | When | |---|---| | nominal auth login --api-key sk_... | Scripts / CI / machines | | nominal auth login | Interactive OAuth (browser, PKCE) | | nominal auth login --no-browser | OAuth device code (SSH / headless) | | nominal auth signup --email … --password … | Bootstrap a fresh account from an agent (no browser, no human) |

OAuth credentials live at ~/.nominal/credentials.json (mode 0600) and auto-refresh before expiry. nominal auth status reports the active source.

For account lifecycle operations beyond signup/login (verify email, reset password, update profile, delete account, notification settings) — use the web console. They're available via nominal api call <op> if you really need them from the CLI, but they're not first-class commands.

Telemetry

Anonymous usage telemetry is on by default. One event per command (name, flag names, exit code, duration, CLI/Node/OS versions, workspace ID, auth method class). Never argument values, credentials, or user identity.

nominal telemetry status         # see exactly what's collected and where it goes
nominal telemetry disable        # opt out (persisted)
NOMINAL_TELEMETRY=0 nominal ...  # per-invocation opt-out
DO_NOT_TRACK=1 nominal ...       # universal opt-out

Full details: PRIVACY.md.

Exit codes

| Code | Meaning | |---|---| | 0 | Success | | 1 | General error | | 2 | Usage error (bad flag, missing arg) | | 3 | Authentication error | | 4 | Rate limit or plan upgrade required | | 5 | Timeout | | 6 | Network error | | 130 | Interrupted (Ctrl-C / SIGINT) |

See ERRORS.md for the per-scenario reference.

Documentation

• skill/SKILL.md — agent-facing usage reference
• AGENTS.md — contributor guide for agents writing code in this repo
• ERRORS.md — error scenarios and messages

Development

npm install
npm run codegen      # fetch spec from $NOMINAL_API_DOMAIN/v1/doc
npm run typecheck
npm run lint
npm run test
npm run build        # codegen + esbuild → dist/nominal.mjs

The HTTP client is generated at build time from the OpenAPI spec. Top-level commands hand-craft the agent UX on top of it.

License

MIT