NinesDocumentation
Search becomes available when JavaScript loads. All chapters are listed in the navigation.
GitHub
Browse documentation
View Markdown

Nines CLI

nines is a single Go executable with native Cobra commands, generated help and shell completion. cobra-cli is Cobra's optional contributor scaffolding generator; users need neither generator nor Go after the binary is built. Run make cli, bin/nines --help, or bin/nines intent conversations approve --help.

  • Existing single-dash long flags remain accepted; new examples use normal double-dash flags.
  • Flags may precede or follow positional arguments.
  • Unknown or irrelevant leaf flags fail instead of being ignored.

Without a Nines server

These commands use the same validation and rule compiler as the server. They do not contact a server or load a credential store:

sh
nines init slo --name checkout --window 28d --step 1m --out checkout.yaml
nines validate --offline -f checkout.yaml --agent
nines rules generate --offline -f checkout.yaml --tenant commerce --out rules.yaml
nines operator crds --offline > crds.yaml
nines operator render --offline -f checkout.yaml --namespace team-commerce > slo.kubernetes.yaml
nines capabilities --offline --agent
nines skills show nines-cli --offline > SKILL.md
  • -f - reads stdin; file inputs retain their command-specific size limits.
    • Generated files use exclusive creation and do not overwrite an existing file.
    • Offline validate supports SLOs, critical user journeys, measurement bindings, dependency maps and intent YAML.
    • SLO override flags apply only to SLO definitions; intent validation does not select or confirm a measurement. Offline validation proves declared schema/numerical validity.
    • For query-backed SLOs it also parses PromQL, requires instant-vector results and checks the generated recording and alert expressions.
    • It cannot prove metric presence, result cardinality, provider evaluation, business semantics or a CUJ's end-to-end success.
    • Offline rule generation renders YAML without deploying it.
    • For operator render --rules-only, supply an explicit --tenant or NINES_TENANT; Kubernetes namespace and Nines tenant are separate identities.
  • nines integration SLO_ID --agent reads separate definition, collection, rule deployment and live external evaluation states.
    • It does not deploy or reload anything.
    • Provider errors and unavailable runtime APIs remain unverified. rules apply returns configuration persistence plus separate activation and evaluation stages.
    • A successful HTTP response or state: written does not establish activation: inspect these fields, including failed reload, manual reload, pending and not-loaded states.
    • Standalone Prometheus can opt into rules.reload: true on its trusted connection; this changes the reviewed digest. See automatic backend activation.
  • Connected planning, telemetry discovery, backtests, collection, intent conversations, rule deployment and live status require Nines. --offline rejects those commands before credential loading or requests. There is no implicit in-process server, local database, provider discovery or LLM invocation.

Tenant contexts and API keys

sh
nines config set-context production \
  --server https://nines.example.com --tenant commerce
nines config use-context production
# Inject NINES_API_KEY through your shell or CI secret manager.
nines login --method api-key --context production
nines auth status --context production --agent
nines get slos --context production -o table
nines get slos --context production --agent
  • NINES_API_KEY is preferred, with API_TOKEN retained as an alias. If both exist, NINES_API_KEY wins.
    • Keys are read at invocation time, never accepted as command-line values, printed in status, or written by login.
    • Existing server API grants and managed service-account keys both work.
    • CI and deterministic skills should normally use an appropriately scoped service-account key, including an agent/viewer role where sufficient.
    • Environment keys are explicitly usable with a different server/tenant selector; the server still enforces their grants.
    • Never point a credential-bearing invocation at an untrusted server.
  • For server and tenant, explicit flags override NINES_URL/NINES_TENANT, then the selected context, then the existing loopback/default fallback. --context overrides NINES_CONTEXT, then currentContext.
    • Configuration path precedence is --config, NINES_CONFIG, then the OS user configuration directory's nines/config.yaml (on macOS, ~/Library/Application Support/nines/config.yaml).
    • Config is YAML with apiVersion: nines.dev/v1alpha1, kind: CLIConfig, and named {server, tenant} contexts. config get-contexts reads no credentials.
  • Saved browser credentials are considered only if no environment key is present, and only for an exact saved server and tenant match.
    • Changing either selector never forwards a saved browser credential to the new destination. Expired credentials require explicit login.
    • No command silently starts authentication or refreshes a session.

Browser SSO and LDAP login

sh
nines login --method sso --context production --timeout 5m
# Print a URL instead of opening the default browser:
nines login --method sso --context production --no-browser --timeout 5m
nines auth status --context production
nines auth logout --context production
  • The server must have identity authentication enabled. Unset API-key environment variables before explicitly selecting SSO. --method auto (the default) selects an environment API key when present and browser login otherwise.
  • The browser opens Nines' CLI authorization page, where the user signs in through the configured OIDC provider or LDAP directory, sees the exact tenant, current role, server and loopback return address, then explicitly authorizes the CLI.
    • This reuses the existing provider and role mappings. Microsoft Entra ID uses OIDC.
    • SAML-only upstream providers require an OIDC identity broker; native SAML is not implemented.
    • No provider client secret, IdP access token, ID token, password or browser cookie is copied to the CLI.
    • The credential follows its original browser session: logout, session expiry or a changed/removed authenticating provider invalidates it.
    • Changes to current tenant roles are applied on each request.
    • Secret rotation alone does not invalidate the session.
  • The Nines authorization-code exchange uses a random loopback port, state and S256 PKCE.
    • Requests expire in five minutes and approved codes in one minute; codes are consumed atomically once.
    • A resulting opaque credential is restricted to the selected tenant and expires within one hour or the browser session's earlier deadline.
    • Every API request resolves current membership/team/SSO grants and the original session epoch/expiry.
    • Role reductions and browser sign-out revoke access.
    • Upstream IdP changes retain the existing configured claim-freshness limit; this adds no continuous-access or refresh-token promise.
  • A separate .credentials.json file beside config stores only the Nines credential and its server/tenant/expiry binding.
    • The directory requires mode 0700, files mode 0600; writes use a lock, a temporary file and atomic rename.
    • Existing unsafe or symlink file paths are refused.
    • This is private-file storage, not OS-keychain encryption.
    • Coordinate concurrent invocations through the supplied lock; a crash can leave a .lock file that must be inspected and removed after verifying no writer remains.
  • auth logout revokes the saved credential and removes it locally, without signing out the browser or revoking service-account/environment keys.
    • An unavailable server leaves the credential in place so revocation can be retried. auth logout --local deliberately removes only the local copy; the server copy expires normally.
    • Environment API keys remain active until unset or revoked through the server's administrative flow.
  • --no-browser still requires opening the URL on the computer running the CLI because the return address is loopback.
    • For remote headless/CI sessions, use an API key.
    • Device-code login, automatic refresh and OS-keychain storage are not implemented.

Scripts and LLM skills

sh
nines capabilities --agent > capabilities.json
nines skills show nines-cli --offline > SKILL.md
nines search --context production --kind slo --query checkout --agent
nines plan --context production -f reviewed.yaml --agent > plan.json
nines apply --context production -f reviewed.yaml --expected-revision 0 --agent
  • --agent selects JSON for data and errors, prohibits browser login, and never prompts.
    • It does not infer permission to mutate resources or disable model calls on commands explicitly marked as such.
    • The offline capability catalog exposes modes, possible effects, flags, defaults and artifact formats; it grants no authorization.
    • It does not evaluate a skill or invoke an LLM.
    • Exact revisions, intent versions, measurement confirmation and reviewed rule digests remain mandatory. Server role restrictions remain authoritative.
  • Successful data goes to stdout; login instructions and errors go to stderr.
    • Main buffers output until successful completion. --output json|yaml gives structured data with canonical API field names.
    • List commands default to tables for humans; operational results default to JSON.
    • Manifest, Kubernetes and rule exports always emit YAML, including in agent mode; explicit incompatible output flags fail.
    • With --out, the artifact goes to the exclusively created file; human mode prints its path and agent mode emits a JSON CLIArtifact receipt with path, size and SHA-256. skills show defaults to Markdown (JSON with --agent or explicit structured output). history -o csv preserves its existing time-series CSV contract. No ANSI styling is emitted.
    • Unknown values in human tables read unknown.
ExitMeaning
0Success
1Local execution or validation failure
2Invalid command/flag/argument usage
3Missing, invalid or expired authentication
4Tenant or operation forbidden
5Revision/digest/configuration conflict
6API unavailable, timeout or cancellation
  • Agent errors use {apiVersion, kind: CLIError, error: {code, message, exitCode}}.
    • API response bodies and credentials are excluded from errors.
    • The CLI blocks redirects and requires HTTPS, except loopback HTTP for development. --timeout bounds the command; provider/SDK operations may impose shorter limits. No mutation is automatically retried.
    • After an ambiguous timeout, read back current revisions or the intent apply receipt before deciding whether to retry the exact reviewed request.
  • Deterministic here means typed inputs, the shared compiler, stable ordering, explicit side-effect classes and revision/digest checks.
    • It does not mean byte-reproducible live telemetry, timestamps or optional model output.
    • Native resource types retain the shared nines.dev/v1alpha1 YAML contract.
  • Generate shell completion with nines completion bash|zsh|fish|powershell. Install the generated script in the shell's completion directory according to that shell's instructions; running generation does not modify shell configuration.
  • See testing and verification limits for required clean-checkout and external-provider checks.
  • For the controller image, CRD installation, provider prerequisites and ownership boundaries, see the operator guide. Offline rendering does not install a controller or synchronize resources into the portal.
  • See PromQL validation for examples, shared API/operator behavior and the limits of offline checks.
  • Operator-backed connections use the same rules plan and rules apply commands.
    • Their plans include Kubernetes resource YAML and ownership/generation preconditions. rules withdraw --id SLO_ID --expected-digest REVIEWED_DIGEST removes only an owned operator publication while preserving the portal definition and data.
    • Pending cleanup retains the route pin; refresh/review and repeat withdrawal after cleanup to release it. See portal publishing.

Intent decision audit and rollback

  • intent conversations audit ID reads the tenant-scoped decision log and frozen recommendation evidence. reject ID -f request.yaml rejects a proposal or withdraws approval with an exact digest, current conversation version, confirm: true and a reason.
  • rollback-plan, rollback-approve, rollback-apply and rollback-reject use explicit operational YAML through the same context/authentication contract.
    • Rollback appends configuration revisions, rejects intervening edits and does not deploy external rules.
    • Newly created resources have no previous revision and produce a blocked rollback. rollback-kubernetes ID --namespace NAME --digest SHA256 exports exact restore definitions for a separate GitOps review.
  • See recommendation review, audit and rollback for request sequencing, approval notes, permission boundaries and production limitations. Machine output mode does not reduce the privileges of the configured credential; assistants should use the server's agent role.

Archived SLO revisions

  • Measurement selectors, service, source, sampling interval and binding references can be edited under the same SLO name. plan reports measurementChanged and reset/deployment warnings.
    • Apply with the current expected revision; old measurement evidence is archived atomically and is not reused by the new measurement.
    • Binding provenance must still match the declared query contract.
  • nines history SLO --revision 1 --range 1h --resolution 1m --agent reads a replaced revision's original definition and retained observations. Omit --revision for current history. Inspect definition history through GET /api/slos/SLO/revisions and GET /api/slos/SLO/revisions/1. See SLO editing.

Verify an SLO-owned measurement

Prefer one self-contained SLO YAML with spec.measurement. Offline validation and rule generation derive selectors deterministically. Connected telemetry verification is read-only:

sh
nines telemetry verify -f examples/request-success.slo.yaml --context production --agent
  • It returns the SLO manifest and digests with recent source metadata/series evidence; it creates no binding or SLO and deploys no rules.
    • Use plan and the existing revision-fenced apply afterward.
    • MCP verify_slo_measurement and Go CompileMeasurement use the same endpoint.
    • For an inline intent conversation, confirmation YAML uses measurementDigest, intentDigest, expectedVersion and confirm: true, with no binding. Only owner/editor roles can confirm. See measurements.

Automatic rule deployment controls

  • For an owner-configured automatic source, saved SLO revisions reconcile without rules apply.
    • The playground enables this by default; other deployments opt in with rules.autoDeploy: true. integration includes durable automation progress and failure evidence.
    • Owners can pause/resume one SLO using an exact revision:
sh
nines rules pause --id checkout-success --expected-revision 2 --agent
nines rules resume --id checkout-success --expected-revision 2 --agent
  • Pause retains loaded rules and survives PostgreSQL-backed restarts and SLO edits. Resume queues the current saved definition. These owner controls neither edit nor approve an SLO. See automatic rule delivery.

Read recent SLO measurements

  • nines collect SLO_ID --recent --context CONTEXT --agent reads a bounded recent range from the SLO's configured source using the server clock.
    • It commits measurement data without changing the SLO definition or deploying rules.
    • Editors and owners may collect; this is a write operation in the command catalog.
    • Explicit --from and --to remain available for backfills and cannot be combined with --recent.
    • A returned collected: 0 means no measurement rows matched, not a successful SLI calculation.
    • Inspect the source's metric names and labels in the portal before changing a selector.

Decision audit journal

  • Owners/editors can search tenant decisions with nines audit list --agent, inspect a frozen proposal with nines audit show RECORD_ID --agent, or export matching full records with nines audit export --agent (NDJSON).
    • All use the selected server/tenant context; offline mode rejects them.
    • Filters include actor subject, resource, conversation, action, outcome and RFC3339 from/to dates.
    • Check export exit status before retaining the output.
    • Approvals require a nonempty review reason through every client, and a different owner/editor subject must apply that approval or rollback.
    • The bundled CLI skill describes these boundaries.
    • See governance for pagination, ambiguous apply outcomes and archive limitations.

SLO templates

  • Use nines --offline templates list --category agent, nines templates show agent-task-completion and nines templates generate agent-task-completion --out task.slo.yaml.
    • The shared catalog covers request serving, pipelines, storage, agents, LLMs and inference.
    • Generated manifests start as experimental SLOs with illustrative metrics and targets. --values accepts strict YAML overrides; --agent returns a machine-readable draft receipt.
    • Rendering never verifies telemetry, applies resources or deploys rules. See SLI menus and templates for the complete workflow.

Declarative extensions

  • Use nines --offline extensions test -f bundle.yaml, extensions install --file bundle.yaml --sha256 EXPECTED_DIGEST --lock extensions.lock.yaml, and templates generate EXTENSION--RECIPE --extension-lock extensions.lock.yaml --values values.yaml. Explicit HTTPS installation supports --url.
    • Git installation uses --git REPOSITORY --commit FULL_COMMIT_ID --git-path bundles/extension.yaml with the same trusted --sha256.
    • Public HTTPS repositories and existing local clones are supported; --offline permits local clones and forbids remote downloads.
    • The operator renderer accepts the same --template, --extension-lock and --values inputs. See extension authoring, distribution and tenant configuration.

Kubernetes dependency discovery

  • dependencies import-kubernetes --offline --namespace commerce -f resources.yaml --out map.yaml projects a local Kubernetes export into a reviewable dependency map without loading credentials or contacting a server.
    • Omit --out for a JSON receipt with candidate evidence and warnings. dependencies discover --namespace commerce --context production --agent requests an explicitly enabled namespace through the Nines server's in-cluster reader.
    • Both commands only preview; review the map and use the normal revision-checked plan/apply flow to save it.
    • See service dependencies for permissions, annotations, limitations and the visual editor.

Retire objectives

  • Use nines retire plan ID --action archive --agent to inspect references and the exact revision/digest, then nines retire apply ID --action archive --expected-revision REVISION --digest DIGEST --agent. retire status reads the durable cleanup/audit receipt; retire retry retries the original owned cleanup when due.
    • Permanent deletion needs a separate --action delete plan and --confirm-name ID.
    • Mutations require a tenant owner; offline mode is refused.
    • See SLO retirement for retained history, reference resolution and recovery.

Visual evidence and recording deletion

  • nines visual assess JOURNEY requires an exact --revision, fixed request --id, --route-digest from reviewed capabilities, --image, --criterion and explicit --consent. See visual journey evidence for privacy and idempotency semantics.
  • nines visual list JOURNEY reads bounded receipts. nines visual review JOURNEY EVALUATION --digest ... --outcome ... --reason ... saves a separate immutable owner/editor review. Neither command publishes SLI data.
  • nines replays ingest requires an owner or editor to attest both capture and tenant-sharing consent. Agent-role credentials cannot grant those attestations.
  • nines replays delete ID --expected-version N --confirm-id ID permanently removes the native stored recording with owner permission. It does not delete exports or backups.
  • --agent does not authorize consent. Agents must obtain explicit permission from the responsible human before sending images or deleting recordings.

Resumable headless workflows

  • nines intent conversations status ID --context production --agent returns the saved phase, next action, exact version/digests, human review gate and recorded observation outcome.
  • nines intent conversations report ID --context production --agent emits a verified JSON snapshot. Add --markdown for a portable Markdown attachment; share its potentially sensitive definitions and review notes only with authorized recipients.
  • Status is read-only. It does not call a model, query telemetry or authorize mutation. Unknown states require inspection; a committed configuration is not marked healthy.
  • Read the headless workflow guide for the full prepare/review/apply/verify/rollback sequence and executable CLI acceptance test.

GitHub review evidence

  • nines intent conversations github-plan ID prepares a stable review plan for an explicit repository, PR number and full head commit without contacting GitHub.
  • github-publish ID requires the exact reviewed conversation version, change-set digest, report digest and --confirm-sharing. Set NINES_GITHUB_TOKEN privately; it is distinct from Nines authentication.
  • Comments are immutable evidence snapshots, not approval or application. See GitHub reviews for consent, retries, concurrency limits and the opt-in Actions example.

Native provider evidence

  • nines native results SLO_ID --from RFC3339 --to RFC3339: on-demand current native Datadog/New Relic evidence, separate from Nines calculations.
  • nines native list CONNECTION: bounded native catalog on the configured destination.
  • nines native draft CONNECTION --native-id ID --name NAME --project PROJECT --service SERVICE: experimental YAML for normal plan/apply review. No vendor mutation or ownership adoption. --agent retains the draft envelope and limitations; ordinary YAML output sends limitations to stderr.
  • These are connected, read-only operations. Offline mode prohibits them. Provider limits apply.