CLI Reference

Complete reference documentation for the Stark Orchestrator command-line interface.

General Usage

node packages/cli/dist/index.js <command> [subcommand] [options]

Global Options

Option	Description
`-o, --output <format>`	Output format: `json`, `table`, or `plain`
`-k, --insecure`	Accept self-signed SSL certificates
`-h, --help`	Display help
`--version`	Display version

Authentication Commands

`auth setup`

Create the initial admin user. Only works when no users exist.

stark auth setup

Prompts for email, password, and optional display name.

`auth login`

Login to the orchestrator.

stark auth login --email user@example.com

Option	Description
`--email, -e`	User email address
`--password, -p`	Password (prompts if not provided)

`auth logout`

Logout from the orchestrator.

stark auth logout

`auth whoami`

Display current user information.

stark auth whoami

`auth add-user`

Create a new user (admin only).

stark auth add-user --email newuser@example.com --role node

Option	Description	Default
`--email, -e`	User email address	(required)
`--password, -p`	Password (prompts if not provided)	-
`--role, -r`	User role: admin, user, node, viewer	`user`

`auth list-users`

List all users (admin only).

stark auth list-users

Pack Commands

`pack bundle`

Bundle source code into a deployable pack.

stark pack bundle <source> --out <output>

Argument/Option	Description
`<source>`	Source file or directory
`--out, -o`	Output bundle file path

Examples:

# Bundle a single file
stark pack bundle ./app.js --out ./bundle.js

# Bundle a Nuxt project
stark pack bundle ./my-nuxt-app --out ./nuxt-bundle.js

`pack register`

Register a bundle as a pack.

stark pack register <bundle> --name <name> --ver <version> --runtime <runtime>

Option	Description	Default
`--name, -n`	Pack name	(required)
`--ver, -V`	Pack version (semver)	(required)
`--runtime, -r`	Runtime type: `node` or `browser`	(required)
`--visibility`	Visibility: `private` or `public`	`private`
`--min-node-version`	Minimum Node.js version required	-
`-y, --yes`	Skip confirmation prompts	`false`

Note: For Node.js runtime packs, if --min-node-version is not specified, you will be prompted to confirm using your current system Node.js version. Use -y to skip the prompt (no minimum version will be set).

Examples:

# Register a private Node.js pack
stark pack register ./bundle.js --name my-app --ver 1.0.0 --runtime node

# Explicit version requirement
stark pack register ./bundle.js --name my-app --ver 1.0.0 --runtime node --min-node-version 20.0.0

# Without version - prompts for confirmation
stark pack register ./bundle.js --name my-app --ver 1.0.0 --runtime node
# ⚠ No minimum Node.js version specified.
# ℹ Current system Node.js version: 22.5.1
# Use current Node.js version (22.5.1) as minimum? [y/N]

# Skip prompt (no minimum version set)
stark pack register ./bundle.js --name my-app --ver 1.0.0 --runtime node -y

# Register a public browser pack
stark pack register ./ui-bundle.js --name my-ui --ver 1.0.0 --runtime browser --visibility public

`pack list`

List all registered packs.

stark pack list

`pack versions`

List all versions of a pack.

stark pack versions <pack-name>

Pod Commands

`pod create`

Create and deploy a pod.

stark pod create --pack <name> [options]

Option	Description	Default
`--pack, -P`	Pack name to deploy	(required)
`--ver, -V`	Pack version	latest
`--node, -n`	Target specific node	auto-scheduled
`--namespace`	Target namespace	`default`
`--priority, -p`	Priority (0-1000)	`100`
`--label, -l`	Pod label `key=value` (repeatable)	-
`--replicas, -r`	Number of replicas	`1`
`--node-selector, -s`	Node selector `key=value` (repeatable)	-
`--toleration, -t`	Toleration `key=value:effect` (repeatable)	-
`--cpu`	CPU request in millicores	`100`
`--memory`	Memory request in MB	`128`
`--volume`	Volume mount `name:/mount/path` (repeatable)	-

Examples:

# Simple pod
stark pod create --pack my-app --node my-node

# Pod with volume mount
stark pod create volume-counter \
  --node production-node-1 \
  --volume counter-data:/app/data

# Pod with constraints
stark pod create --pack my-app \
  --node-selector env=production \
  --toleration dedicated=gpu:NoSchedule \
  --cpu 500 \
  --memory 256 \
  --priority 200 \
  --label app=web \
  --label version=v1

`pod list`

List all pods.

stark pod list [options]

Option	Description
`--namespace, -n`	Filter by namespace
`--status`	Filter by status

`pod status`

Get detailed pod status.

stark pod status <pod-id>

`pod rollback`

Rollback pod to a previous version.

stark pod rollback <pod-id> --ver <version>

Option	Description
`--ver, -V`	Target version to rollback to

`pod delete`

Delete a pod.

stark pod delete <pod-id>

Service Commands

`service create`

Create a managed service.

stark service create <name> --pack <pack-name> [options]

Option	Description	Default
`--pack, -P`	Pack name to deploy	(required)
`--ver, -V`	Pack version	latest
`--namespace`	Target namespace	`default`
`--replicas, -r`	Number of replicas (0 = all matching nodes)	`1`
`--label, -l`	Service label (repeatable)	-
`--pod-label`	Label for created pods (repeatable)	-
`--node-selector, -s`	Node selector (repeatable)	-
`--toleration, -t`	Toleration (repeatable)	-
`--cpu`	CPU request in millicores	`100`
`--memory`	Memory request in MB	`128`
`--follow-latest`	Auto-update to new pack versions	`false`
`-n, --node <nodeId>`	Target node ID (required for volume mounts)	-
`--volume`	Volume mount `name:/mount/path` (repeatable)	-

Examples:

# Basic service with 3 replicas
stark service create web-app --pack my-app --replicas 3

# Service with shared volume (all replicas on same node)
stark service create log-svc --pack shared-log --replicas 3 \
  --node production-node-1 --volume shared-log:/app/logs

# DaemonSet mode (deploy to all matching nodes)
stark service create gpu-worker --pack ml-pack --replicas 0 --node-selector gpu=true

# Auto-updating service
stark service create canary --pack my-app --follow-latest

`service list`

List all services.

stark service list

`service status`

Get service status.

stark service status <name>

`service scale`

Scale a service.

stark service scale <name> --replicas <count>

Option	Description
`--replicas, -r`	New replica count (0 = DaemonSet mode)

`service pause`

Pause service reconciliation.

stark service pause <name>

`service resume`

Resume service reconciliation.

stark service resume <name>

`service delete`

Delete a service.

stark service delete <name> [--force]

Option	Description
`--force, -f`	Delete without confirmation

Node Commands

`node list`

List all registered nodes.

stark node list

`node status`

Get detailed node status.

stark node status <name>

`node update`

Update node properties.

stark node update <name> [options]

Option	Description
`--label, -l`	Add/update label `key=value` (repeatable)
`--remove-label`	Remove label by key (repeatable)
`--taint`	Add/update taint `key=value:effect` (repeatable)
`--remove-taint`	Remove taint by key (repeatable)
`--unschedulable`	Mark node as unschedulable (cordon)
`--schedulable`	Mark node as schedulable (uncordon)

Examples:

# Add labels
stark node update my-node --label env=production --label tier=frontend

# Cordon a node
stark node update my-node --unschedulable

# Remove a taint
stark node update my-node --remove-taint dedicated

`node rm`

Delete a node.

stark node rm <name>

`node agent start`

Start a node agent.

stark node agent start [options]

Option	Description	Default
`--url, -u`	Orchestrator WebSocket URL	`wss://localhost/ws`
`--name, -n`	Unique node name	hostname
`--token, -t`	Authentication token	-
`--email, -e`	Login email (alternative to token)	-
`--password, -p`	Login password (with email)	-
`--label, -l`	Node label (repeatable)	-
`--taint`	Node taint `key=value:effect` (repeatable)	-
`--cpu`	Allocatable CPU millicores	`1000`
`--memory`	Allocatable memory in MB	`1024`
`--pods`	Maximum concurrent pods	`10`
`--heartbeat`	Heartbeat interval in seconds	`15`

Examples:

# Basic node agent
stark node agent start --url wss://localhost/ws --name my-node

# With authentication
stark node agent start --email user@example.com --password mypass

# With labels and resources
stark node agent start \
  --label env=production \
  --label tier=backend \
  --cpu 2000 \
  --memory 4096 \
  --pods 20

Namespace Commands

`namespace create`

Create a namespace.

stark namespace create <name>

`namespace list`

List all namespaces.

stark namespace list

`namespace delete`

Delete a namespace.

stark namespace delete <name>

Server Config Commands

`server-config set`

Configure server settings (admin only).

stark server-config set [options]

Option	Description
`--enable-registration`	Allow automatic node registration
`--disable-registration`	Require authentication for nodes

Environment Variables

The node agent supports these environment variables:

Variable	Description
`STARK_ORCHESTRATOR_URL`	WebSocket URL
`STARK_NODE_NAME`	Node name
`STARK_AUTH_TOKEN`	Authentication token
`STARK_EMAIL`	Login email
`STARK_PASSWORD`	Login password

Output Formats

All commands support multiple output formats:

# Table format (default)
stark pod list

# JSON format (for scripting)
stark pod list --output json

# Plain text format
stark pod list -o plain

Secret Commands

Manage encrypted secrets for pod injection.

`secret create`

Create a new secret.

stark secret create <name> --type <type> [options]

Option	Description
`--type <type>`	Secret type: `opaque`, `tls`, `docker-registry`
`--from-literal <key=value>`	Add a key-value pair (repeatable)
`--from-file <key=path>`	Read value from file (repeatable)
`--inject <mode>`	Injection mode: `env` or `volume`
`--prefix <prefix>`	Environment variable prefix (env mode)
`--mount-path <path>`	Volume mount path (volume mode)
`--key-mapping <src:dest>`	Remap env var names (repeatable)
`--file-mapping <src:dest>`	Remap filenames in volume (repeatable)
`-n, --namespace <ns>`	Target namespace (default: `default`)

Examples:

# Opaque secret with environment injection
stark secret create db-creds --type opaque \
  --from-literal username=admin \
  --from-literal password=s3cret \
  --inject env --prefix DB_

# TLS secret with volume injection
stark secret create api-cert --type tls \
  --from-file tls.crt=./cert.pem \
  --from-file tls.key=./key.pem \
  --inject volume --mount-path /etc/ssl/certs

# Docker registry credentials
stark secret create registry-auth --type docker-registry \
  --from-literal server=registry.example.com \
  --from-literal username=deploy \
  --from-literal password=token123

Note: Secret values are encrypted at rest and never echoed back.

`secret list`

List all secrets (alias: secret ls).

stark secret list [options]

Option	Description
`-n, --namespace <ns>`	Filter by namespace
`--type <type>`	Filter by type
`-o, --output <format>`	Output format

Example:

stark secret list -n production
# NAME          TYPE              NAMESPACE    KEYS  INJECTION  CREATED
# db-creds      opaque            production   2     env        2 min ago
# api-cert      tls               production   2     volume     5 min ago

`secret get`

Get secret metadata (values are never shown).

stark secret get <name> [options]

Option	Description
`-n, --namespace <ns>`	Namespace to search
`-o, --output <format>`	Output format

`secret update`

Update an existing secret's data or injection config.

stark secret update <name> [options]

Option	Description
`--from-literal <key=value>`	Replace key-value pairs
`--from-file <key=path>`	Replace values from files
`--inject <mode>`	Change injection mode
`--prefix <prefix>`	Update env prefix
`--mount-path <path>`	Update mount path
`-n, --namespace <ns>`	Target namespace

`secret delete`

Delete a secret (alias: secret rm).

stark secret delete <name> [options]

Option	Description
`-n, --namespace <ns>`	Target namespace

Volume Commands

`volume create`

Create a named volume on a node.

stark volume create <name> --node <name-or-uuid>

Option	Description
`--name <name>`	Volume name (alternative to positional arg)
`-n, --node <nameOrId>`	(required) Target node (name or UUID)

Volume names must be lowercase alphanumeric with hyphens, 1–63 characters (^[a-z0-9]([a-z0-9-]*[a-z0-9])?$).

Example:

stark volume create counter-data --node production-node-1

`volume list`

List volumes, optionally filtered by node.

stark volume list [--node <name-or-uuid>]

Alias: stark volume ls

Option	Description
`-n, --node <nameOrId>`	Filter by node (name or UUID)

`volume download`

Download volume contents as a tar archive.

stark volume download <name> --node <name-or-uuid> --output ./backup.tar

Option	Description
`--name <name>`	Volume name (alternative to positional arg)
`-n, --node <nameOrId>`	(required) Node where the volume resides
`-o, --output <path>`	(required) Output file path

Service Integration

Services can reference secrets with the --secret flag:

stark service create my-api \
  --pack my-api --ver 1.0.0 \
  --secret db-creds \
  --secret api-cert

Referenced secrets are resolved, decrypted, and injected into pods at creation time.

Home
Getting Started
- Installation
- Quick Start
Concepts
Core Architecture
Tutorials
Reference
Advanced Topics
Contribution
- Contributing Guide
- Code of Conduct

CLI Reference

CLI Reference

General Usage

Global Options

Authentication Commands

auth setup

auth login

auth logout

auth whoami

auth add-user

auth list-users

Pack Commands

pack bundle

pack register

pack list

pack versions

Pod Commands

pod create

pod list

pod status

pod rollback

pod delete

Service Commands

service create

service list

service status

service scale

service pause

service resume

service delete

Node Commands

node list

node status

node update

node rm

node agent start

Namespace Commands

namespace create

namespace list

namespace delete

Server Config Commands

server-config set

Environment Variables

Output Formats

Secret Commands

secret create

secret list

secret get

secret update

secret delete

Volume Commands

volume create

volume list

volume download

Service Integration

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

`auth setup`

`auth login`

`auth logout`

`auth whoami`

`auth add-user`

`auth list-users`

`pack bundle`

`pack register`

`pack list`

`pack versions`

`pod create`

`pod list`

`pod status`

`pod rollback`

`pod delete`

`service create`

`service list`

`service status`

`service scale`

`service pause`

`service resume`

`service delete`

`node list`

`node status`

`node update`

`node rm`

`node agent start`

`namespace create`

`namespace list`

`namespace delete`

`server-config set`

`secret create`

`secret list`

`secret get`

`secret update`

`secret delete`

`volume create`

`volume list`

`volume download`