CLI Reference

The Neutrino CLI (nno) provides namespaced commands for platform management and feature development.

nno <namespace> <command> [options]

Installation

pnpm add -g @neutrino-io/cli

nno --version

Authentication

Core commands — not namespaced.

nno login

Authenticate with the Neutrino platform.

nno login
nno login --token <api-token>

Notes:

• --token stores credentials immediately and is intended for CI pipelines.
• Interactive login is being rolled out as an OAuth 2.0 device-authorization flow against the NNO IAM service. On the current build it prints guidance and exits cleanly; see nno login for the planned device-flow walkthrough.

Credentials are written atomically to ~/.nno/credentials.json (mode 0600). Use nno whoami to confirm and nno logout to clear.

Examples:

# CI / non-interactive
nno login --token $NNO_API_TOKEN

nno logout

Sign out from the Neutrino platform by clearing the stored credentials file.

nno logout

No flags.

nno whoami

Display the currently authenticated user, platform, and role.

nno whoami

No flags.

Example output:

i Authenticated as developer@acme.com
i Platform: r4xk9m2zt5
i Role: platform-admin

Warns if no credentials are stored or if the token has expired.

Project Management

Commands for local development, building, validation, and deployment of a Neutrino platform project. These commands operate locally against Wrangler and Vite — no Neutrino auth required.

nno project check

Validate project config for the target environment.

nno project check
nno project check --env stg

Checks performed:

Exit codes: 0 success, 2 errors found.

Example:

nno project check --env stg

  ✓ P01  wrangler.toml found (auth, billing)
  ✓ P02  [env.stg] defined in all service configs
  ✓ P03  D1 IDs populated (no placeholders)
  ✓ P04  PLATFORM_ID=r4xk9m2zt5, TENANT_ID=n7wp3fy8q1
  ⚠ P05  VITE_AUTH_API_URL not set in .env.stg

  0 errors, 1 warning(s) — project is deployable with caveats

nno project dev

Start all Neutrino services for local development using concurrently.

nno project dev

No flags.

Starts the following services in parallel:

All services are killed if any one exits (success or failure).

nno project build

Build the console shell for the target environment.

nno project build
nno project build --env prod

Runs pnpm --filter console build --mode <env>. Output goes to apps/console/dist/.

Example:

nno project build --env prod
# → Building console for env: prod
# ✓ Build complete → apps/console/dist/

nno project deploy

Deploy the platform console to Cloudflare Pages via the Neutrino CLI Service.

nno project deploy <platform-id>
nno project deploy <platform-id> --env prod

Calls POST /api/v1/platforms/<platform-id>/deploy on the Neutrino CLI Service and polls for deployment completion (up to 5 minutes). Reads NNO_CLI_SERVICE_URL and NNO_CLI_API_KEY from environment variables.

Example:

nno project deploy r4xk9m2zt5 --env stg
# Triggering deployment for platform r4xk9m2zt5 (stg)...
# Deployment started: dep_9x2m4k7p1q
# URL: https://r4xk9m2zt5-stg.pages.dev
# Polling for completion...
#   Status: deploy — success
# Deployment complete

Feature Development

Commands for scaffolding, developing, testing, validating, and submitting feature packages.

nno feature init

Scaffold a new feature package.

nno feature init <name>
nno feature init analytics --no-service
nno feature init crm --dir ./packages/crm

Generates the full feature scaffold:

<name>/
├── src/
│   ├── feature.ts        ← FeatureDefinition
│   ├── routes/index.tsx  ← Page component
│   └── index.tsx         ← Package entry
├── nno.config.ts
├── package.json
├── tsconfig.json
├── README.md
└── service/              ← Hono Worker (omitted with --no-service)
    ├── src/index.ts
    └── wrangler.toml.template

Example:

nno feature init analytics
# cd analytics
# pnpm install
# nno feature dev

nno feature dev

Start the local feature development environment.

nno feature dev
nno feature dev --no-service
nno feature dev --platform r4xk9m2zt5 --env stg

Default mode starts the Neutrino Mock Shell at localhost:5100 and the feature Vite dev server at localhost:5180. With --platform, the mock shell connects to the real Neutrino auth service.

Port assignments:

nno feature test

Run feature tests with Vitest.

nno feature test
nno feature test --watch
nno feature test --coverage
nno feature test --service-only
nno feature test --ui-only

nno feature build

Build the feature package for distribution using tsup.

nno feature build
nno feature build --analyze

Output goes to dist/.

nno feature validate

Validate a feature package for Neutrino compatibility. Must pass before nno feature submit.

nno feature validate
nno feature validate ./packages/analytics

Validation checks:

Exit codes: 0 all checks passed, 1 one or more checks failed.

Example:

nno feature validate
# Validating feature at /projects/analytics...
#
#   ✓ package.json exists
#   ✓ package.json has "neutrino": {"type": "feature"}
#   ✓ exports featureManifest
#   ✓ TypeScript compiles without errors
#   ✓ Permission keys follow {featureId}:{action} format
#
# Result: 5 passed, 0 failed

nno feature submit

Authorship policy (current): feature authorship is restricted to Neutrino. Per ADR-006, the Neutrino platform does not accept client-submitted feature packages today; the nno feature commands are intended for Neutrino contributors. External users should activate the Neutrino-authored feature catalogue via stack templates instead.

Submit the feature package for distribution.

nno feature submit
nno feature submit --message "Initial submission"
nno feature submit --private
nno feature submit --dry-run

Requires authentication (nno login) and a passing nno feature validate.

nno feature status

Authorship policy (current): restricted to Neutrino contributors per ADR-006. The submission pipeline is internal to Neutrino.

Check submission status.

nno feature status
nno feature status <submission-id>

Statuses: PENDING → IN_REVIEW → APPROVED | REJECTED

Plugin System

The Neutrino CLI uses a plugin-based namespace registry. Each domain (project, feature) is a self-contained NnoPlugin registered at startup.

NnoPlugin interface (packages/cli/src/types.ts):

import type { SubCommandsDef } from "citty";

export interface NnoPlugin {
  /** Namespace name — becomes the top-level subcommand (e.g. 'project'). */
  name: string;
  /** Short description shown in `nno --help`. */
  description?: string;
  /** Citty subcommands for this namespace. */
  commands: SubCommandsDef;
}

Authoring an external plugin:

import { definePlugin, registerPlugin } from "@neutrino-io/cli/plugin";
import { defineCommand } from "citty";

export const analyticsPlugin = definePlugin({
  name: "analytics",
  description: "Analytics management commands",
  commands: {
    report: defineCommand({
      meta: { name: "report", description: "Generate analytics report" },
      async run() {
        // ...
      },
    }),
  },
});

// Register before runMain in your entry point
registerPlugin(analyticsPlugin);

Built-in namespaces: project, feature. Planned namespaces (Phase 2): platform, ops.

Exit Codes

Environment Variables

Credentials are stored in ~/.nno/credentials.json after nno login.