NNO CLI

nno <namespace> <command> [options]

# Global install (recommended)
npm install -g @neutrino-io/cli
# or
pnpm add -g @neutrino-io/cli

# Verify
nno --version

packages/
└── cli/                  ← single binary + plugin registry
    └── src/
        ├── index.ts      ← register plugins + runMain
        ├── cli.ts        ← registerPlugin(), createCli()
        ├── types.ts      ← NnoPlugin interface, definePlugin()
        ├── plugins/
        │   ├── project.ts      ← nno project namespace
        │   ├── feature.ts      ← nno feature namespace
        │   └── marketplace.ts  ← nno marketplace namespace
        ├── commands/
        │   ├── auth/           ← login, logout, whoami (core, not namespaced)
        │   ├── project/        ← check, dev, build, deploy
        │   ├── feature/        ← init, dev, test, build, validate, submit, status
        │   └── marketplace/    ← list
        └── utils/
            ├── credentials.ts
            └── exec.ts

import type { SubCommandsDef } from 'citty'

export interface NnoPlugin {
  name: string                // namespace (top-level CLI command)
  description?: string
  commands: SubCommandsDef    // citty subcommands
}

export function definePlugin(plugin: NnoPlugin): NnoPlugin

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

const analyticsPlugin = definePlugin({
  name: 'analytics',
  description: 'Analytics management',
  commands: {
    report: defineCommand({ ... }),
  },
})

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

import { runMain } from 'citty'
import { registerPlugin, createCli } from './cli.js'
import { projectPlugin }     from './plugins/project.js'
import { featurePlugin }     from './plugins/feature.js'
import { marketplacePlugin } from './plugins/marketplace.js'

registerPlugin(projectPlugin)
registerPlugin(featurePlugin)
registerPlugin(marketplacePlugin)

runMain(createCli())

nno login      # interactive login to NNO account
nno logout
nno whoami     # show current auth status

nno whoami
# → Authenticated as [email protected]
# → Platform: r4xk9m2zt5 (Foresight)
# → Role: platform-admin

nno project check   [--env <local|dev|stg|prod>]
nno project dev     [--service <name|all>] [--env <local|dev>]
nno project build   [--env <stg|prod>]
nno project deploy  [--service <name|all>] [--env <stg|prod>]

nno project check --env stg

nno project check --env stg

  Checking project config for env: stg

  ✓ P01  wrangler.toml found (auth, console)
  ✓ 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 for stg — set in CF Pages dashboard
  ⚠ P06  AUTH_SECRET not set for stg — run: nno project deploy --env stg (will prompt)
  ✓ P08  Pages project name follows convention

  0 errors, 2 warnings — project is deployable with caveats

nno project dev                         # start all services
nno project dev --service auth          # auth worker only
nno project dev --env dev               # target dev CF environment

nno project dev
  │
  ├─ nno project check --env local
  ├─ Apply pending local D1 migrations (wrangler d1 migrations apply --local)
  │
  ├─ wrangler dev  (platform auth Worker)                     → localhost:8787  (per-platform auth)
  │    Note: services/auth/ is a TEMPLATE with REPLACE_WITH_* placeholders —
  │    it is NOT deployed from this repo. Each platform project supplies its
  │    own deployed auth Worker; local dev starts a wrangler instance of it.
  └─ vite dev (apps/console)                                  → localhost:5174
       └─ /api/auth proxied to localhost:8787

nno project build --env stg
nno project build --env prod

nno project build --env stg
  │
  ├─ nno project check --env stg
  └─ vite build --mode stg  (apps/console)
       → outputs apps/console/dist/

nno project deploy --env stg
nno project deploy --env prod
nno project deploy --env stg --service auth     # single service only

nno project deploy --env stg
  │
  ├─ nno project check --env stg
  ├─ nno project build --env stg
  │
  ├─ wrangler deploy --env stg  (services/auth/)              (per-platform auth)
  │
  ├─ wrangler d1 migrations apply --env stg --remote  (if P07 flagged pending)
  │
  └─ wrangler pages deploy apps/console/dist
       --project-name=r4xk9m2zt5-n7wp3fy8q1-portal-stg
       --branch=develop

nno feature init      <feature-name> [options]
nno feature dev       [--no-service] [--platform <id>] [--env <dev|stg>]
nno feature test      [--watch] [--coverage]
nno feature build     [--analyze]
nno feature validate  [--fix] [--json]
nno feature submit    [--message <msg>] [--private] [--dry-run]
nno feature status    [<submission-id>]

nno feature init analytics
nno feature init inventory --no-service
nno feature init crm --dir ./packages/ui-crm

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

nno feature dev
  │
  ├─ NNO Mock Shell     localhost:5100   (ShellContextProvider + mock user/tenant)
  ├─ Feature Vite Dev   localhost:5180   (mounted inside mock shell, full HMR)
  └─ Wrangler Service   localhost:8790   (local D1, hot-restart)

{
  "platform": { "id": "dev-platform", "name": "Local Dev Platform" },
  "tenant":   { "id": "dev-tenant",   "name": "Local Dev Tenant" },
  "user": { "id": "dev-user", "email": "[email protected]", "permissions": ["*"] }
}

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

nno feature build
nno feature build --analyze

dist/
├── index.js        ← UI package (ESM)
├── index.d.ts      ← Type declarations
├── feature.js      ← FeatureDefinition (tree-shakeable)
└── service/
    └── worker.js   ← Compiled Hono Worker (if service present)

nno feature validate
nno feature validate --fix
nno feature validate --json

nno feature submit
nno feature submit --message "Initial submission — analytics v1"
nno feature submit --private
nno feature submit --dry-run

nno feature submit
  ├─ nno feature validate    (fails fast on errors)
  ├─ nno feature build
  ├─ Package dist/ + nno.config.ts + README.md → submission bundle (.nno)
  ├─ Upload to NNO Marketplace review queue
  └─ Returns submission ID + tracking URL

nno feature status                   # all pending submissions for your platform
nno feature status sub_9x2m4k7p1q   # specific submission

nno marketplace list     [--search <term>]
nno marketplace approve  <submission-id>
nno marketplace reject   <submission-id> [--reason <msg>]

nno platform deploy  --platform <id> --env <stg|prod> [--wait]
nno platform status  --platform <id>
nno platform tenants --platform <id>

{
  "apiUrl": "https://api.stack.nno.app",
  "defaultPlatform": "r4xk9m2zt5",
  "defaultEnv": "stg"
}

jobs:
  validate-and-test:
    steps:
      - run: npm install -g @neutrino-io/cli
      - run: pnpm install
      - run: nno feature validate --json
      - run: nno feature test --coverage
      - run: nno feature build

jobs:
  deploy-stg:
    if: github.ref == 'refs/heads/develop'
    steps:
      - run: nno project check --env stg
      - run: nno project deploy --env stg

  deploy-prod:
    if: github.ref == 'refs/heads/main'
    steps:
      - run: nno project check --env prod
      - run: nno project deploy --env prod

✗ Error [V08]: serviceEnvKey is required when requiresService is true

  Add serviceEnvKey to your FeatureDefinition:
  → serviceEnvKey: 'VITE_ANALYTICS_API_URL'

  Docs: https://docs.nno.app/sdk/feature-definition#serviceenvkey