@nebulaos/cli 0.1.0

package/README.md

@@ -0,0 +1,298 @@
+# 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, inspect execution results and logs
+- **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
+
+```bash
+# 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
+
+```bash
+# 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"}'
+```
+
+## 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.
+
+```bash
+# 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
+
+```bash
+# 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](https://github.com/sindresorhus/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) |
+| `nebulaos exec list` | List executions |
+| `nebulaos exec get <id>` | Get execution details |
+| `nebulaos exec logs <id>` | View execution logs |
+
+### 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.
+
+```bash
+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.
+
+```bash
+nebulaos resources list -o json
+```
+
+```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.
+
+```bash
+nebulaos resources list -o yaml
+```
+
+```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.
+
+```bash
+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](docs/ai-usage.md) for the complete guide on machine-friendly usage, including JSON output parsing, pagination, and automation patterns.
+
+## Documentation
+
+- [Command Reference](docs/commands.md) -- Detailed reference for all commands with examples
+- [AI Agent Usage Guide](docs/ai-usage.md) -- Guide for AI agent integration and automation
+
+## License
+
+Proprietary - StaryaAI