NebulaOS CLI

Command-line interface for managing NebulaOS AI agents, workflows, and resources.

Features

• Authentication -- Login with Personal Access Tokens (PAT), manage contexts for multiple organizations
• Resource Management -- List, inspect, archive, unarchive, and promote agents, workflows, and tools
• Execution -- Run agents and workflows remotely, with optional memory context for multi-turn conversations
• LLM Gateway -- Manage routes, API keys, browse model catalog, track usage and requests
• RAG -- Create and manage Retrieval-Augmented Generation connections, run semantic searches
• Feature Flags -- Enable, disable, and configure platform features
• Observability -- Search and inspect traces, view metrics
• Multi-format Output -- Table, JSON, YAML, and quiet modes for both humans and AI agents

Installation

# npm
npm install -g @nebulaos/cli

# pnpm
pnpm add -g @nebulaos/cli

# yarn
yarn global add @nebulaos/cli

After installation, the nebulaos command will be available globally.

Quick Start

# 1. Login with your Personal Access Token
nebulaos auth login

# 2. Check authentication status
nebulaos auth status

# 3. List your organizations
nebulaos orgs list

# 4. List registered resources
nebulaos resources list

# 5. Execute an agent
nebulaos exec run <resourceId> --input '{"prompt": "Hello"}'

# 6. Multi-turn conversation (same memory-key = same context)
nebulaos exec run <resourceId> -i '"Hello"' -m my-session
nebulaos exec run <resourceId> -i '"What did I just say?"' -m my-session

Configuration

Contexts

NebulaOS CLI supports multiple contexts, allowing you to manage several organizations or environments. Each context stores an API URL, authentication token, and organization ID.

# Login creates a context automatically
nebulaos auth login --api-url https://api.myorg.nebulaos.com --context-name production

# Switch between organizations
nebulaos orgs switch my-other-org

# View all configuration
nebulaos config list

Defaults

# Set default output format
nebulaos config set defaults.output json

# Set default page size (1-100)
nebulaos config set defaults.pageSize 50

Configuration is stored using the conf library under the nebulaos project name (~/.config/nebulaos/config.json on Linux).

Environment Variables

| Variable | Description | Corresponding Flag | |---|---|---| | NEBULAOS_OUTPUT | Default output format (table, json, yaml, quiet) | -o, --output | | NEBULAOS_CONTEXT | Context name to use | --context | | NEBULAOS_API_URL | Override API URL | --api-url | | NEBULAOS_TOKEN | Override authentication token | --token | | NEBULAOS_ORG_ID | Override organization ID | --org-id |

Global Options

These options are available on every command:

| Option | Description | |---|---| | -o, --output <format> | Output format: table, json, yaml, quiet | | --context <name> | Use a specific context | | --api-url <url> | Override API URL | | --token <token> | Override authentication token | | --org-id <id> | Override organization ID | | --no-color | Disable colored output | | --verbose | Enable verbose output | | -V, --version | Show CLI version | | -h, --help | Show help |

Commands

Authentication

| Command | Description | |---|---| | nebulaos auth login | Authenticate with a Personal Access Token | | nebulaos auth logout | Remove credentials for a context | | nebulaos auth status | Show current authentication status |

Organizations

| Command | Description | |---|---| | nebulaos orgs list | List accessible organizations | | nebulaos orgs get <id> | Get organization details | | nebulaos orgs switch <slug> | Switch active organization context |

Clients

| Command | Description | |---|---| | nebulaos clients list | List clients in the current organization | | nebulaos clients get <id> | Get client details (including agents and workflows) | | nebulaos clients create | Create a new client | | nebulaos clients api-keys list <clientId> | List API keys for a client | | nebulaos clients api-keys create <clientId> | Create a new API key | | nebulaos clients api-keys revoke <clientId> <keyId> | Revoke an API key |

Resources

| Command | Description | |---|---| | nebulaos resources list | List registered resources (agents, workflows, tools) | | nebulaos resources get <id> | Get resource details | | nebulaos resources archive <id> | Archive a resource | | nebulaos resources unarchive <id> | Unarchive a resource | | nebulaos resources promote <id> | Promote a resource from discovered to official |

Execution

| Command | Description | |---|---| | nebulaos exec run <resourceId> | Execute a resource (agent or workflow) with optional memory context | | nebulaos exec list | List executions | | nebulaos exec get <id> | Get execution details | | nebulaos exec logs <id> | View execution logs |

Multi-turn conversations:

# Use --memory-key (-m) to maintain context across executions
nebulaos exec run my-agent -i '"Olá"' -m session-123
nebulaos exec run my-agent -i '"Qual foi minha última mensagem?"' -m session-123

LLM Gateway

| Command | Description | |---|---| | nebulaos llm routes list | List all LLM gateway routes | | nebulaos llm routes get <alias> | Get route details | | nebulaos llm routes create | Create a new route | | nebulaos llm routes update <alias> | Update a route | | nebulaos llm routes delete <alias> | Delete a route | | nebulaos llm keys list | List LLM gateway API keys | | nebulaos llm keys create | Create a new LLM API key | | nebulaos llm keys revoke <keyId> | Revoke an LLM API key | | nebulaos llm catalog | Browse the LLM model catalog | | nebulaos llm requests | List recent LLM gateway requests | | nebulaos llm usage | Show LLM gateway usage statistics |

RAG

| Command | Description | |---|---| | nebulaos rag connections list | List RAG connections | | nebulaos rag connections get <id> | Get connection details | | nebulaos rag connections create | Create a new RAG connection | | nebulaos rag connections update <id> | Update a RAG connection | | nebulaos rag connections delete <id> | Delete a RAG connection | | nebulaos rag connections test <id> | Test a RAG connection | | nebulaos rag search | Search using RAG |

Features

| Command | Description | |---|---| | nebulaos features catalog | List all available features in the catalog | | nebulaos features list | List enabled features | | nebulaos features get <key> | Get feature details | | nebulaos features enable <key> | Enable a feature | | nebulaos features disable <key> | Disable a feature | | nebulaos features config <key> | View or update feature configuration |

Observability

| Command | Description | |---|---| | nebulaos obs traces search | Search traces | | nebulaos obs traces get <traceId> | Get trace details | | nebulaos obs metrics | View observability metrics |

Config

| Command | Description | |---|---| | nebulaos config list | List all configuration values | | nebulaos config get <key> | Get a configuration value | | nebulaos config set <key> <value> | Set a configuration value |

Output Formats

Table (default)

Human-readable formatted tables with colored output.

nebulaos resources list

 ID                                    Name           Type    Status      Created At
 550e8400-e29b-41d4-a716-446655440000  my-agent       agent   official    1/15/2026
 6ba7b810-9dad-11d1-80b4-00c04fd430c8  my-workflow     workflow discovered  1/20/2026

JSON

Machine-readable JSON, ideal for scripting and AI agent integration.

nebulaos resources list -o json

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "my-agent",
    "type": "agent",
    "status": "official",
    "createdAt": "2026-01-15T10:30:00.000Z"
  }
]

YAML

YAML output for configuration-friendly contexts.

nebulaos resources list -o yaml

- id: 550e8400-e29b-41d4-a716-446655440000
  name: my-agent
  type: agent
  status: official
  createdAt: "2026-01-15T10:30:00.000Z"

Quiet

Outputs only IDs, one per line. Useful for piping to other commands.

nebulaos resources list -o quiet
# 550e8400-e29b-41d4-a716-446655440000
# 6ba7b810-9dad-11d1-80b4-00c04fd430c8

Exit Codes

| Code | Meaning | |---|---| | 0 | Success | | 1 | General error | | 2 | Invalid argument | | 3 | Authentication error | | 4 | Authorization error | | 5 | Not found | | 6 | Conflict error | | 7 | Validation error | | 8 | Network error | | 9 | Timeout error | | 10 | Server error | | 11 | Configuration error |

For AI Agents

This CLI is designed to be used by AI agents (Claude, Cursor, etc.). See docs/ai-usage.md for the complete guide on machine-friendly usage, including JSON output parsing, pagination, and automation patterns.

Documentation

• Command Reference -- Detailed reference for all commands with examples
• AI Agent Usage Guide -- Guide for AI agent integration and automation

License

Proprietary - StaryaAI