@nebulaos/cli 0.1.0 → 0.1.2

package/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-present, iamkun
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,298 +1,310 @@
-# 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
+# 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
+
+```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"}'
+
+# 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.
+
+```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) 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:**
+
+```bash
+# 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.
+
+```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