diff --git a/README.md b/README.md index d7d3bad..171b8e4 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,20 @@ # nbctl: Nudgebee CLI +[![CI](https://github.com/nudgebee/nbctl/actions/workflows/ci.yml/badge.svg)](https://github.com/nudgebee/nbctl/actions/workflows/ci.yml) +[![Release](https://img.shields.io/github/v/release/nudgebee/nbctl)](https://github.com/nudgebee/nbctl/releases/latest) +[![License](https://img.shields.io/github/license/nudgebee/nbctl)](LICENSE) +[![Go Version](https://img.shields.io/github/go-mod/go-version/nudgebee/nbctl)](go.mod) + `nbctl` is a powerful command-line interface for seamless interaction with the Nudgebee API. It allows you to manage various Nudgebee resources directly from your terminal, providing a convenient way to automate tasks, query data, and integrate with your workflows. ## Features -* **Comprehensive API Access**: Interact with Nudgebee accounts, events, logs, metrics, optimizations, and traces. -* **Nubi Integration**: Create and manage Nubi (Nudgebee's AI assistant) configurations. +* **Comprehensive API Access**: Interact with Nudgebee accounts, events, logs, metrics, traces, optimizations, security recommendations, SLOs, workflows, tickets, and audit logs. +* **Workflow Lifecycle**: Apply, trigger, pause/resume, cancel, and inspect workflow executions from the command line. +* **Events & Troubleshooting**: List events, inspect event-manager rules and triage rules, and explore deduplication chains. +* **Tickets**: Create tickets in external systems (Jira, ServiceNow, PagerDuty, GitHub, GitLab, Zenduty) through configured integrations. +* **Nubi Integration**: Create and manage Nubi (Nudgebee's AI assistant) configurations and run an interactive AI shell. +* **MCP Server**: Expose all `nbctl` capabilities as Model Context Protocol tools for use with Claude Desktop and other LLM clients. * **Flexible Output**: View results in human-readable text or machine-parseable JSON format. * **Shell Autocompletion**: Generate completion scripts for Bash, Zsh, Fish, and PowerShell for enhanced productivity. * **Configurable Logging**: Control the verbosity and level of logging for debugging and monitoring. @@ -13,7 +22,7 @@ ## Installation -To install `nbctl`, ensure you have Go installed (version 1.16 or higher). Then, run the following command: +To install `nbctl`, ensure you have Go installed (version 1.25 or higher). Then, run the following command: ```bash go install github.com/nudgebee/nbctl@latest @@ -43,6 +52,40 @@ sudo mv nbctl-darwin-arm64 /usr/local/bin/nbctl After downloading, make sure the binary is executable and moved to a directory included in your system's `PATH` (e.g., `/usr/local/bin`). +## Quickstart + +Once `nbctl` is on your `PATH`, get to your first command in under a minute: + +```bash +# 1. Configure your credentials (interactive — you'll need an API key from your Nudgebee profile) +nbctl configure add default + +# 2. Verify everything works +nbctl accounts list + +# 3. Try something useful — events from the last 24 hours +nbctl events list --limit 10 +``` + +Useful follow-ups from here: + +```bash +# Inspect a specific event (replace with an ID from the list above) +nbctl events get + +# Look at the rules that fire events +nbctl events list-rules --limit 10 + +# See what optimization recommendations exist for your cluster +nbctl optimizations list --limit 10 + +# Trigger a workflow +nbctl workflow list +nbctl workflow trigger +``` + +Most commands accept `--format json` for scripting and `--help` for full flag documentation. See the [Usage](#usage) section below for the full command reference. + ## Configuration Before using most `nbctl` commands, you need to configure your Nudgebee API credentials. `nbctl` supports managing multiple configuration profiles, allowing you to easily switch between different Nudgebee environments or user accounts. @@ -337,6 +380,32 @@ Example: nbctl accounts list --status active --cloud-provider aws --name "production" ``` +#### `nbctl audit-logs` + +Query audit events recorded for the current account. + +##### `nbctl audit-logs list` + +Lists audit events, ordered by most recent first. + +* **Flags**: + * `--account-id `: Account ID (overrides the active profile). + * `--username `: Filter by username (exact match). + * `--category `: Filter by event category (e.g. `AUTO_PILOT`). + * `--type `: Filter by event type. + * `--action `: Filter by event action (e.g. `UPDATE`). + * `--status `: Filter by event status (e.g. `SUCCESS`). + * `--start-time `: Filter events after this timestamp. + * `--end-time `: Filter events before this timestamp. + * `--limit `: Maximum number of events to return. Default is 25. + * `--offset `: Pagination offset. Default is 0. + +Example: + +```bash +nbctl audit-logs list --category AUTO_PILOT --status SUCCESS --limit 50 +``` + #### `nbctl events` Manages Nudgebee events, allowing you to list, search, and describe them. If no subcommand is provided, it defaults to `list`. @@ -377,6 +446,50 @@ Example: nbctl events list --account-id 123e4567-e89b-12d3-a456-426614174000 --status "open" --start-time "2023-10-26T00:00:00Z" --limit 50 ``` +##### `nbctl events list-rules` + +Lists event-manager rules (Prometheus / alert-manager style rules that determine which conditions raise an event). + +* **Flags**: + * `--account-id `: Account ID (overrides the active profile). + * `--name `: Filter by alert name (case-insensitive partial match). + * `--limit `: Maximum number of rules to return. Default is 25. + * `--offset `: Pagination offset. Default is 0. + +Example: + +```bash +nbctl events list-rules --name "PostgreSQL" --limit 10 +``` + +##### `nbctl events list-triage-rules` + +Lists event triage rules — both system rules and user-defined rules that classify or route incoming events. + +* **Flags**: + * `--account-id `: Account ID (overrides the active profile). + * `--rule-type `: Filter by rule type (e.g. `scoring`, `suppression`). + * `--enabled`: Filter by enabled status. Pass `--enabled` to filter enabled rules; `--enabled=false` for disabled. + +Example: + +```bash +nbctl events list-triage-rules --enabled --rule-type scoring +``` + +##### `nbctl events list-duplicates ` + +Shows the deduplication chain for an event — every occurrence the system has linked together via fingerprint matching. Prints a friendly message when the event has no duplicates. + +* **Arguments**: + * `` (required): The unique identifier of the event. + +Example: + +```bash +nbctl events list-duplicates 2934c445-f776-4a8b-9234-a1faefe71058 +``` + #### `nbctl logs` Queries logs from the Nudgebee API. @@ -590,6 +703,87 @@ Example: nbctl security list-image-cves --severity Critical --namespace production ``` +#### `nbctl slo` + +Query Service Level Objective (SLO) configurations and compliance reports. + +##### `nbctl slo list` + +Lists SLO configurations for the current account. + +* **Flags**: + * `--account-id `: Account ID (overrides the active profile). + * `--workload `: Filter by workload name (exact match). + * `--namespace `: Filter by workload namespace (exact match). + * `--enabled`: Filter by enabled status. Pass `--enabled` for enabled SLOs; `--enabled=false` for disabled. + +Example: + +```bash +nbctl slo list --namespace nudgebee-test --enabled +``` + +##### `nbctl slo get ` + +Fetches a single SLO configuration. Use `--report` to also fetch the latest compliance report (burn rate, event budgets, status). + +* **Arguments**: + * `` (required): The unique identifier of the SLO config. +* **Flags**: + * `--account-id `: Account ID (overrides the active profile). + * `--report`: Also fetch the latest compliance report. + +Example: + +```bash +nbctl slo get a5f07f40-d2f0-4edf-91c7-96ddb0b25ae8 --report +``` + +#### `nbctl tickets` + +List ticket integration configurations and create tickets in external systems (Jira, ServiceNow, PagerDuty, GitHub, GitLab, Zenduty). + +##### `nbctl tickets list-configurations` + +Lists configured ticket integrations for the current account. Filters to ticket-capable integration types by default. + +* **Flags**: + * `--type `: Filter by a single integration type (`jira`, `github`, `gitlab`, `servicenow`, `pagerduty`, `zenduty`). Validated client-side. + * `--status `: Filter by status (e.g. `enabled`). + +Example: + +```bash +nbctl tickets list-configurations --type jira --status enabled +``` + +##### `nbctl tickets create` + +Creates a ticket via a configured integration. + +* **Flags**: + * `--integration-id ` (required): The integration configuration ID. Use `tickets list-configurations` to find it. + * `--title ` (required): Ticket title. + * `--project-key ` (required): Project / board key in the external system. + * `--description `: Ticket description / body. + * `--ticket-type `: Issue type (e.g. `Bug`, `Task`). + * `--severity `: Severity / priority. + * `--assignee `: Assignee identifier. + * `--reference-id `: Reference linking this ticket to a Nudgebee event. + * `--source `: Source system identifier. + * `--additional-fields `: Additional integration-specific fields as a JSON object. + +Example: + +```bash +nbctl tickets create \ + --integration-id 100d48eb-6503-4bf1-8474-be3441804284 \ + --title "Pod crashloop in prod" \ + --project-key OPS \ + --severity high \ + --reference-id +``` + #### `nbctl traces` Queries traces from the Nudgebee API. @@ -648,25 +842,151 @@ Example: nbctl integrations list --type jira --status enabled ``` +#### `nbctl workflow` + +Manage workflows: list, inspect, apply (create or update from YAML), trigger executions, pause/resume, cancel in-flight executions, and inspect execution history. + +##### `nbctl workflow list` + +Lists all workflows. + +* **Flags**: + * `--account-id `: Account ID (overrides the active profile). + * `--status `: Filter by workflow status (e.g. `ACTIVE`, `PAUSED`). + * `--last-execution-status `: Filter by last execution status. + * `--type `: Filter by workflow type. + +Example: + +```bash +nbctl workflow list --status ACTIVE +``` + +##### `nbctl workflow get ` + +Fetches workflow details including the full definition. + +Example: + +```bash +nbctl workflow get 6e8e1a30-a306-4635-90c5-ac16611f3677 +``` + +##### `nbctl workflow apply ` + +Creates or updates a workflow from a YAML file (upsert). + +Example: + +```bash +nbctl workflow apply ./my-workflow.yaml +``` + +##### `nbctl workflow validate ` + +Server-side validation of a workflow YAML without creating or updating anything. + +Example: + +```bash +nbctl workflow validate ./my-workflow.yaml +``` + +##### `nbctl workflow delete ` + +Deletes a workflow by ID. + +Example: + +```bash +nbctl workflow delete 6e8e1a30-a306-4635-90c5-ac16611f3677 +``` + +##### `nbctl workflow trigger ` + +Triggers a workflow execution. Returns the new execution ID. + +* **Flags**: + * `-i, --input `: Pass workflow inputs. Repeatable. + +Example: + +```bash +nbctl workflow trigger 6e8e1a30-a306-4635-90c5-ac16611f3677 -i name=alice -i count=3 +``` + +##### `nbctl workflow pause ` / `nbctl workflow resume ` + +Pause an active workflow (stops accepting new triggers) or resume a paused one. + +Example: + +```bash +nbctl workflow pause 6e8e1a30-a306-4635-90c5-ac16611f3677 +nbctl workflow resume 6e8e1a30-a306-4635-90c5-ac16611f3677 +``` + +##### `nbctl workflow list-executions ` + +Lists execution history for a specific workflow with optional filters and pagination. + +* **Flags**: + * `--account-id `: Account ID (overrides the active profile). + * `--status `: Filter by execution status (e.g. `COMPLETED`, `FAILED`). + * `--trigger-type `: Filter by trigger type. + * `--limit `: Maximum number of executions to return. + * `--page-token `: Pagination token from a previous response. + +Example: + +```bash +nbctl workflow list-executions 6e8e1a30-a306-4635-90c5-ac16611f3677 --status COMPLETED --limit 10 +``` + +##### `nbctl workflow get-execution ` + +Fetches a single workflow execution including its tasks, inputs, outputs, and any errors. + +Example: + +```bash +nbctl workflow get-execution 6e8e1a30-a306-4635-90c5-ac16611f3677 019e8cde-38f4-75e2-93cb-de8278183926 +``` + +##### `nbctl workflow cancel-execution ` + +Cancels a specific in-progress execution. + +Example: + +```bash +nbctl workflow cancel-execution 6e8e1a30-a306-4635-90c5-ac16611f3677 019e8cde-38f4-75e2-93cb-de8278183926 +``` + ## Testing -Unit tests use the helpers in `pkg/testutil` to mock the API and avoid network calls. Integration tests are gated and will only run when explicitly enabled. +Unit tests use the helpers in `pkg/testutil` to mock the API and avoid network calls. Integration (end-to-end) tests live behind a build tag and are only compiled when explicitly requested. - Run unit tests: ```bash +make test +# or go test ./... ``` -- Run integration tests (manual): +- Run end-to-end tests against a live Nudgebee environment: ```bash -export NUDGEBEE_INTEGRATION=1 export NUDGEBEE_ENDPOINT=https://app.nudgebee.com export NUDGEBEE_API_KEY= -go test ./... -run Integration +make test-e2e +# or +NUDGEBEE_INTEGRATION=1 go test -tags=e2e ./... ``` +Individual e2e tests will `t.Skip` themselves if `NUDGEBEE_ENDPOINT` or `NUDGEBEE_API_KEY` is unset, so they're safe to run without env vars (they just won't actually exercise anything). + ## Contributing We welcome contributions. See [CONTRIBUTING.md](./CONTRIBUTING.md)