From 2e9b2fdc9c3183557aa598b0f8afb6f40e8c34f4 Mon Sep 17 00:00:00 2001 From: Boris Ovcjak Date: Tue, 1 Sep 2026 21:04:07 +0200 Subject: [PATCH 01/25] feat: migrate CLI to Databox V2 API (1.0.0) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Complete transition from V1 to V2 API — no V1 calls remain. - API client: V2 envelope unwrapping, added patch/put methods, x-account-id header support - Migrated all 15 existing commands to V2 paths and response shapes - Added ~65 new commands covering full V2 surface (profile, billing, users, clients, connections, integrations, metrics, activity-log, databoards, plus new data-source and dataset sub-commands) - Renamed account list → account info (V2 returns single account) - Dataset IDs now numeric (validated client-side) - primaryKeys → primaryKey, schema name → columnId - Global --account-id flag for multi-account access - 123 tests (68 new + 36 updated), all passing - Updated README with 86 commands, 11 skills - Added CHANGELOG.md with full migration guide - Version bump 0.3.1 → 1.0.0 Co-Authored-By: Claude Opus 4.6 (1M context) --- CHANGELOG.md | 180 ++ README.md | 2169 +++++++++++++++-- package.json | 2 +- skills/databox-account/SKILL.md | 50 + skills/databox-accounts/SKILL.md | 49 - skills/databox-analyze/SKILL.md | 10 +- skills/databox-billing/SKILL.md | 24 + skills/databox-clients/SKILL.md | 36 + skills/databox-connections/SKILL.md | 30 + skills/databox-data-sources/SKILL.md | 53 +- skills/databox-datasets/SKILL.md | 74 +- skills/databox-integrations/SKILL.md | 26 + skills/databox-metrics/SKILL.md | 43 + skills/databox-users/SKILL.md | 32 + src/base-command.ts | 10 + src/commands/account/data-sources.ts | 47 +- src/commands/account/datasets.ts | 47 +- src/commands/account/info.ts | 27 + src/commands/account/list.ts | 35 - src/commands/account/timezones.ts | 7 +- src/commands/account/update.ts | 32 + src/commands/account/usage.ts | 17 + src/commands/activity-log/list.ts | 73 + src/commands/auth/login.ts | 2 +- src/commands/auth/validate.ts | 2 +- src/commands/billing/info.ts | 17 + src/commands/billing/invoices.ts | 64 + src/commands/client/create.ts | 27 + src/commands/client/delete.ts | 37 + src/commands/client/get.ts | 25 + src/commands/client/list.ts | 61 + src/commands/client/update.ts | 36 + src/commands/connection/delete.ts | 37 + src/commands/connection/get.ts | 25 + src/commands/connection/list.ts | 66 + src/commands/connection/permissions.ts | 25 + src/commands/connection/set-permissions.ts | 31 + src/commands/connection/update.ts | 36 + src/commands/data-source/create.ts | 34 +- src/commands/data-source/datasets.ts | 33 +- src/commands/data-source/delete.ts | 2 +- src/commands/data-source/get.ts | 28 + src/commands/data-source/list.ts | 64 + src/commands/data-source/permissions.ts | 32 + src/commands/data-source/purge.ts | 43 + src/commands/data-source/set-permissions.ts | 35 + .../data-source/set-sync-frequency.ts | 30 + src/commands/data-source/set-timezone.ts | 30 + src/commands/data-source/sync-frequencies.ts | 48 + src/commands/data-source/update.ts | 34 + src/commands/databoard/list.ts | 66 + src/commands/databoard/metrics.ts | 25 + src/commands/dataset/add-modification.ts | 37 + src/commands/dataset/clear-modifications.ts | 44 + src/commands/dataset/column-metadata.ts | 43 + src/commands/dataset/create.ts | 20 +- src/commands/dataset/data.ts | 68 + src/commands/dataset/delete.ts | 16 +- src/commands/dataset/duplicate.ts | 29 + src/commands/dataset/get.ts | 19 +- src/commands/dataset/ingest.ts | 14 +- src/commands/dataset/ingestion-statistics.ts | 29 + src/commands/dataset/ingestion.ts | 10 +- src/commands/dataset/ingestions.ts | 20 +- src/commands/dataset/list.ts | 67 + src/commands/dataset/metadata.ts | 29 + src/commands/dataset/modifications.ts | 43 + src/commands/dataset/permissions.ts | 29 + src/commands/dataset/purge.ts | 16 +- src/commands/dataset/schema.ts | 45 + src/commands/dataset/set-column-metadata.ts | 37 + src/commands/dataset/set-metadata.ts | 38 + src/commands/dataset/set-permissions.ts | 34 + src/commands/dataset/set-sync-frequency.ts | 31 + src/commands/dataset/set-timezone.ts | 31 + src/commands/dataset/set-verification.ts | 36 + src/commands/dataset/sync-frequencies.ts | 46 + src/commands/dataset/sync-history.ts | 70 + src/commands/dataset/update.ts | 35 + src/commands/dataset/verification.ts | 29 + src/commands/integration/get.ts | 25 + src/commands/integration/list.ts | 65 + src/commands/metric/create.ts | 33 + src/commands/metric/data.ts | 46 + src/commands/metric/delete.ts | 37 + src/commands/metric/dimension-values.ts | 42 + src/commands/metric/drilldown.ts | 34 + src/commands/metric/get.ts | 25 + src/commands/metric/list.ts | 69 + src/commands/metric/set-verification.ts | 31 + src/commands/metric/update.ts | 35 + src/commands/metric/usages.ts | 25 + src/commands/metric/verification.ts | 25 + src/commands/profile/info.ts | 28 + src/commands/profile/update.ts | 33 + src/commands/user/delete.ts | 37 + src/commands/user/get.ts | 25 + src/commands/user/invite.ts | 29 + src/commands/user/list.ts | 63 + src/commands/user/update.ts | 31 + src/lib/api-client.ts | 40 +- test/commands/account/data-sources.test.ts | 32 +- test/commands/account/datasets.test.ts | 31 +- .../account/{list.test.ts => info.test.ts} | 16 +- test/commands/account/timezones.test.ts | 11 +- test/commands/account/update.test.ts | 33 + test/commands/account/usage.test.ts | 34 + test/commands/activity-log/list.test.ts | 35 + test/commands/auth/login.test.ts | 8 +- test/commands/auth/validate.test.ts | 10 +- test/commands/billing/info.test.ts | 34 + test/commands/billing/invoices.test.ts | 35 + test/commands/client/create.test.ts | 33 + test/commands/client/delete.test.ts | 27 + test/commands/client/get.test.ts | 33 + test/commands/client/list.test.ts | 34 + test/commands/client/update.test.ts | 33 + test/commands/connection/delete.test.ts | 31 + test/commands/connection/get.test.ts | 37 + test/commands/connection/list.test.ts | 34 + test/commands/connection/permissions.test.ts | 31 + .../connection/set-permissions.test.ts | 31 + test/commands/connection/update.test.ts | 31 + test/commands/data-source/create.test.ts | 16 +- test/commands/data-source/datasets.test.ts | 22 +- test/commands/data-source/delete.test.ts | 11 +- test/commands/data-source/get.test.ts | 25 + test/commands/data-source/list.test.ts | 42 + test/commands/data-source/permissions.test.ts | 24 + test/commands/data-source/purge.test.ts | 24 + .../data-source/set-permissions.test.ts | 24 + .../data-source/set-sync-frequency.test.ts | 24 + .../commands/data-source/set-timezone.test.ts | 24 + .../data-source/sync-frequencies.test.ts | 28 + test/commands/data-source/update.test.ts | 24 + test/commands/databoard/list.test.ts | 34 + test/commands/databoard/metrics.test.ts | 38 + .../commands/dataset/add-modification.test.ts | 18 + .../dataset/clear-modifications.test.ts | 18 + test/commands/dataset/column-metadata.test.ts | 22 + test/commands/dataset/create.test.ts | 16 +- test/commands/dataset/data.test.ts | 26 + test/commands/dataset/delete.test.ts | 10 +- test/commands/dataset/duplicate.test.ts | 19 + test/commands/dataset/get.test.ts | 30 +- test/commands/dataset/ingest.test.ts | 18 +- .../dataset/ingestion-statistics.test.ts | 22 + test/commands/dataset/ingestion.test.ts | 20 +- test/commands/dataset/ingestions.test.ts | 28 +- test/commands/dataset/list.test.ts | 32 + test/commands/dataset/metadata.test.ts | 18 + test/commands/dataset/modifications.test.ts | 22 + test/commands/dataset/permissions.test.ts | 18 + test/commands/dataset/purge.test.ts | 10 +- test/commands/dataset/schema.test.ts | 23 + .../dataset/set-column-metadata.test.ts | 18 + test/commands/dataset/set-metadata.test.ts | 18 + test/commands/dataset/set-permissions.test.ts | 18 + .../dataset/set-sync-frequency.test.ts | 18 + test/commands/dataset/set-timezone.test.ts | 18 + .../commands/dataset/set-verification.test.ts | 18 + .../commands/dataset/sync-frequencies.test.ts | 22 + test/commands/dataset/sync-history.test.ts | 22 + test/commands/dataset/update.test.ts | 18 + test/commands/dataset/verification.test.ts | 18 + test/commands/env-concurrency.test.ts | 3 +- test/commands/integration/get.test.ts | 39 + test/commands/integration/list.test.ts | 34 + test/commands/metric/create.test.ts | 28 + test/commands/metric/data.test.ts | 33 + test/commands/metric/delete.test.ts | 22 + test/commands/metric/dimension-values.test.ts | 27 + test/commands/metric/drilldown.test.ts | 32 + test/commands/metric/get.test.ts | 22 + test/commands/metric/list.test.ts | 36 + test/commands/metric/set-verification.test.ts | 22 + test/commands/metric/update.test.ts | 22 + test/commands/metric/usages.test.ts | 22 + test/commands/metric/verification.test.ts | 22 + test/commands/profile/info.test.ts | 34 + test/commands/profile/update.test.ts | 33 + test/commands/user/delete.test.ts | 27 + test/commands/user/get.test.ts | 34 + test/commands/user/invite.test.ts | 33 + test/commands/user/list.test.ts | 35 + test/commands/user/update.test.ts | 34 + 186 files changed, 7368 insertions(+), 589 deletions(-) create mode 100644 CHANGELOG.md create mode 100644 skills/databox-account/SKILL.md delete mode 100644 skills/databox-accounts/SKILL.md create mode 100644 skills/databox-billing/SKILL.md create mode 100644 skills/databox-clients/SKILL.md create mode 100644 skills/databox-connections/SKILL.md create mode 100644 skills/databox-integrations/SKILL.md create mode 100644 skills/databox-metrics/SKILL.md create mode 100644 skills/databox-users/SKILL.md create mode 100644 src/commands/account/info.ts delete mode 100644 src/commands/account/list.ts create mode 100644 src/commands/account/update.ts create mode 100644 src/commands/account/usage.ts create mode 100644 src/commands/activity-log/list.ts create mode 100644 src/commands/billing/info.ts create mode 100644 src/commands/billing/invoices.ts create mode 100644 src/commands/client/create.ts create mode 100644 src/commands/client/delete.ts create mode 100644 src/commands/client/get.ts create mode 100644 src/commands/client/list.ts create mode 100644 src/commands/client/update.ts create mode 100644 src/commands/connection/delete.ts create mode 100644 src/commands/connection/get.ts create mode 100644 src/commands/connection/list.ts create mode 100644 src/commands/connection/permissions.ts create mode 100644 src/commands/connection/set-permissions.ts create mode 100644 src/commands/connection/update.ts create mode 100644 src/commands/data-source/get.ts create mode 100644 src/commands/data-source/list.ts create mode 100644 src/commands/data-source/permissions.ts create mode 100644 src/commands/data-source/purge.ts create mode 100644 src/commands/data-source/set-permissions.ts create mode 100644 src/commands/data-source/set-sync-frequency.ts create mode 100644 src/commands/data-source/set-timezone.ts create mode 100644 src/commands/data-source/sync-frequencies.ts create mode 100644 src/commands/data-source/update.ts create mode 100644 src/commands/databoard/list.ts create mode 100644 src/commands/databoard/metrics.ts create mode 100644 src/commands/dataset/add-modification.ts create mode 100644 src/commands/dataset/clear-modifications.ts create mode 100644 src/commands/dataset/column-metadata.ts create mode 100644 src/commands/dataset/data.ts create mode 100644 src/commands/dataset/duplicate.ts create mode 100644 src/commands/dataset/ingestion-statistics.ts create mode 100644 src/commands/dataset/list.ts create mode 100644 src/commands/dataset/metadata.ts create mode 100644 src/commands/dataset/modifications.ts create mode 100644 src/commands/dataset/permissions.ts create mode 100644 src/commands/dataset/schema.ts create mode 100644 src/commands/dataset/set-column-metadata.ts create mode 100644 src/commands/dataset/set-metadata.ts create mode 100644 src/commands/dataset/set-permissions.ts create mode 100644 src/commands/dataset/set-sync-frequency.ts create mode 100644 src/commands/dataset/set-timezone.ts create mode 100644 src/commands/dataset/set-verification.ts create mode 100644 src/commands/dataset/sync-frequencies.ts create mode 100644 src/commands/dataset/sync-history.ts create mode 100644 src/commands/dataset/update.ts create mode 100644 src/commands/dataset/verification.ts create mode 100644 src/commands/integration/get.ts create mode 100644 src/commands/integration/list.ts create mode 100644 src/commands/metric/create.ts create mode 100644 src/commands/metric/data.ts create mode 100644 src/commands/metric/delete.ts create mode 100644 src/commands/metric/dimension-values.ts create mode 100644 src/commands/metric/drilldown.ts create mode 100644 src/commands/metric/get.ts create mode 100644 src/commands/metric/list.ts create mode 100644 src/commands/metric/set-verification.ts create mode 100644 src/commands/metric/update.ts create mode 100644 src/commands/metric/usages.ts create mode 100644 src/commands/metric/verification.ts create mode 100644 src/commands/profile/info.ts create mode 100644 src/commands/profile/update.ts create mode 100644 src/commands/user/delete.ts create mode 100644 src/commands/user/get.ts create mode 100644 src/commands/user/invite.ts create mode 100644 src/commands/user/list.ts create mode 100644 src/commands/user/update.ts rename test/commands/account/{list.test.ts => info.test.ts} (53%) create mode 100644 test/commands/account/update.test.ts create mode 100644 test/commands/account/usage.test.ts create mode 100644 test/commands/activity-log/list.test.ts create mode 100644 test/commands/billing/info.test.ts create mode 100644 test/commands/billing/invoices.test.ts create mode 100644 test/commands/client/create.test.ts create mode 100644 test/commands/client/delete.test.ts create mode 100644 test/commands/client/get.test.ts create mode 100644 test/commands/client/list.test.ts create mode 100644 test/commands/client/update.test.ts create mode 100644 test/commands/connection/delete.test.ts create mode 100644 test/commands/connection/get.test.ts create mode 100644 test/commands/connection/list.test.ts create mode 100644 test/commands/connection/permissions.test.ts create mode 100644 test/commands/connection/set-permissions.test.ts create mode 100644 test/commands/connection/update.test.ts create mode 100644 test/commands/data-source/get.test.ts create mode 100644 test/commands/data-source/list.test.ts create mode 100644 test/commands/data-source/permissions.test.ts create mode 100644 test/commands/data-source/purge.test.ts create mode 100644 test/commands/data-source/set-permissions.test.ts create mode 100644 test/commands/data-source/set-sync-frequency.test.ts create mode 100644 test/commands/data-source/set-timezone.test.ts create mode 100644 test/commands/data-source/sync-frequencies.test.ts create mode 100644 test/commands/data-source/update.test.ts create mode 100644 test/commands/databoard/list.test.ts create mode 100644 test/commands/databoard/metrics.test.ts create mode 100644 test/commands/dataset/add-modification.test.ts create mode 100644 test/commands/dataset/clear-modifications.test.ts create mode 100644 test/commands/dataset/column-metadata.test.ts create mode 100644 test/commands/dataset/data.test.ts create mode 100644 test/commands/dataset/duplicate.test.ts create mode 100644 test/commands/dataset/ingestion-statistics.test.ts create mode 100644 test/commands/dataset/list.test.ts create mode 100644 test/commands/dataset/metadata.test.ts create mode 100644 test/commands/dataset/modifications.test.ts create mode 100644 test/commands/dataset/permissions.test.ts create mode 100644 test/commands/dataset/schema.test.ts create mode 100644 test/commands/dataset/set-column-metadata.test.ts create mode 100644 test/commands/dataset/set-metadata.test.ts create mode 100644 test/commands/dataset/set-permissions.test.ts create mode 100644 test/commands/dataset/set-sync-frequency.test.ts create mode 100644 test/commands/dataset/set-timezone.test.ts create mode 100644 test/commands/dataset/set-verification.test.ts create mode 100644 test/commands/dataset/sync-frequencies.test.ts create mode 100644 test/commands/dataset/sync-history.test.ts create mode 100644 test/commands/dataset/update.test.ts create mode 100644 test/commands/dataset/verification.test.ts create mode 100644 test/commands/integration/get.test.ts create mode 100644 test/commands/integration/list.test.ts create mode 100644 test/commands/metric/create.test.ts create mode 100644 test/commands/metric/data.test.ts create mode 100644 test/commands/metric/delete.test.ts create mode 100644 test/commands/metric/dimension-values.test.ts create mode 100644 test/commands/metric/drilldown.test.ts create mode 100644 test/commands/metric/get.test.ts create mode 100644 test/commands/metric/list.test.ts create mode 100644 test/commands/metric/set-verification.test.ts create mode 100644 test/commands/metric/update.test.ts create mode 100644 test/commands/metric/usages.test.ts create mode 100644 test/commands/metric/verification.test.ts create mode 100644 test/commands/profile/info.test.ts create mode 100644 test/commands/profile/update.test.ts create mode 100644 test/commands/user/delete.test.ts create mode 100644 test/commands/user/get.test.ts create mode 100644 test/commands/user/invite.test.ts create mode 100644 test/commands/user/list.test.ts create mode 100644 test/commands/user/update.test.ts diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..671d2d8 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,180 @@ +# Changelog + +## 1.0.0 — V2 API Migration + +**Breaking change**: The CLI now exclusively uses the Databox V2 API. All V1 API calls have been removed. This requires a Databox account with V2 API access. + +### Migration Guide + +#### Authentication + +No changes to the authentication flow. API keys work the same way — `databox auth login` and the `DATABOX_API_KEY` environment variable continue to work as before. + +#### Command Changes — Where Did My Stuff Go? + +Every v0.x command is still supported in some form. Here's exactly where each one moved and what changed: + +| v0.x Command | v1.0 Equivalent | What Changed | +|---|---|---| +| `account list` | `account info` | **Renamed.** V2 returns your own account as a single object. To list accounts you manage, use `client list` (agency/client model). To access a specific account's resources, pass `--account-id` on any command. | +| `account data-sources ACCOUNTID` | `data-source list` or `account data-sources --account-id ID` | **Positional arg removed.** The `ACCOUNTID` arg is replaced by the global `--account-id` flag. Omit it to use your own account. The new `data-source list` command is the preferred way. | +| `account datasets ACCOUNTID` | `dataset list` or `account datasets --account-id ID` | **Same as above.** The new `dataset list` is preferred. `--type` filter removed — merged datasets are not in V2 (deferred to backlog). | +| `account timezones` | `account timezones` | No changes. | +| `data-source create` | `data-source create` | `--account-id` is now a global flag (works on all commands). `--key` flag preserved for third-party integrations (e.g., Datadoo). | +| `data-source datasets ID` | `data-source datasets ID` | No user-facing changes. | +| `data-source delete ID` | `data-source delete ID` | No changes. | +| `dataset create` | `dataset create` | `--primary-keys` renamed to `--primary-key` (singular, still accepts multiple values). Schema column field `name` renamed to `columnId`. See schema example below. | +| `dataset get GUID` | `dataset get NUMERIC_ID` | **IDs are now numeric.** Use `dataset list` to find your dataset's numeric ID. | +| `dataset delete GUID` | `dataset delete NUMERIC_ID` | **IDs are now numeric.** | +| `dataset ingest GUID` | `dataset ingest NUMERIC_ID` | **IDs are now numeric.** | +| `dataset ingestion GUID ING_ID` | `dataset ingestion NUMERIC_ID ING_ID` | **Dataset ID is now numeric.** Ingestion ID unchanged. | +| `dataset ingestions GUID` | `dataset ingestions NUMERIC_ID` | **IDs are now numeric.** | +| `dataset purge GUID` | `dataset purge NUMERIC_ID` | **IDs are now numeric.** | +| `analyze ask-genie` | `analyze ask-genie` | No changes (uses separate agentic service). | + +#### New Global Flag + +| Flag | Env Var | Description | +|---|---|---| +| `--account-id` | `DATABOX_ACCOUNT_ID` | Target a specific account for multi-account access (agency/client model). Replaces the `ACCOUNTID` positional arg from v0.x. Works on all commands. | + +#### Schema Definition Change + +v0.x: +```bash +--schema '[{"name":"date","dataType":"datetime"},{"name":"value","dataType":"number"}]' +``` + +v1.0: +```bash +--schema '[{"columnId":"date","dataType":"datetime"},{"columnId":"value","dataType":"number"}]' +``` + +The `name` field was renamed to `columnId` to match the V2 API contract. + +#### Dataset ID Migration + +V1 used GUID identifiers for datasets (e.g., `a1b2c3d4-e5f6-...`). V2 uses numeric IDs (e.g., `12345`). The CLI now validates that dataset IDs are numeric and rejects non-numeric values with a clear error. + +To find the numeric ID for an existing dataset: +```bash +databox dataset list +``` + +#### Summary of Removed Features + +| Feature | Why | Alternative | +|---|---|---| +| Multi-account listing (`account list`) | V2 scopes to the caller's account | `client list` for managed accounts, `account info` for your own | +| `--type` filter on dataset listing | Merged datasets deferred to backlog | All datasets are regular datasets in V2 | +| GUID dataset IDs | Architectural decision — numeric IDs unify data sources and datasets | Use `dataset list` to find numeric IDs | +| `ACCOUNTID` positional arg | Replaced by header-based account scoping | `--account-id` flag (global, works everywhere) | + +### New Commands + +65+ new commands covering the full V2 API surface: + +#### Account +- `account info` — Show your account details +- `account update` — Update account name/settings +- `account usage` — Show usage statistics +- `account timezones` — List supported timezones +- `account data-sources` — List data sources +- `account datasets` — List datasets + +#### Profile +- `profile info` — Show your profile +- `profile update` — Update your name or timezone + +#### Billing +- `billing info` — Show billing and plan details +- `billing invoices` — List invoices + +#### Users +- `user list` — List users in the account +- `user get` — Get user details +- `user invite` — Invite a new user +- `user update` — Update a user's role +- `user delete` — Remove a user + +#### Clients +- `client list` — List client accounts +- `client get` — Get client account details +- `client create` — Create a client account +- `client update` — Update a client account +- `client delete` — Delete a client account + +#### Connections +- `connection list` — List connections +- `connection get` — Get connection details +- `connection update` — Update a connection +- `connection delete` — Delete a connection +- `connection permissions` — Show permissions +- `connection set-permissions` — Update permissions + +#### Integrations +- `integration list` — Browse available integrations +- `integration get` — Get integration details + +#### Data Sources (new sub-commands) +- `data-source list` — List data sources with search and pagination +- `data-source get` — Get data source details +- `data-source update` — Update data source title +- `data-source set-timezone` — Set timezone +- `data-source sync-frequencies` — List available sync frequencies +- `data-source set-sync-frequency` — Set sync frequency +- `data-source permissions` — Show permissions +- `data-source set-permissions` — Update permissions +- `data-source purge` — Purge all data + +#### Datasets (new sub-commands) +- `dataset list` — List datasets with search and pagination +- `dataset update` — Update dataset title +- `dataset duplicate` — Duplicate a dataset +- `dataset data` — View dataset data +- `dataset schema` — View dataset schema +- `dataset set-timezone` — Set timezone +- `dataset sync-frequencies` — List available sync frequencies +- `dataset set-sync-frequency` — Set sync frequency +- `dataset sync-history` — View sync history +- `dataset permissions` — Show permissions +- `dataset set-permissions` — Update permissions +- `dataset metadata` — View metadata +- `dataset set-metadata` — Update metadata +- `dataset column-metadata` — View column metadata +- `dataset set-column-metadata` — Update column metadata +- `dataset verification` — View verification status +- `dataset set-verification` — Toggle verification +- `dataset modifications` — List modifications +- `dataset add-modification` — Add a modification +- `dataset clear-modifications` — Clear all modifications +- `dataset ingestion-statistics` — View ingestion statistics + +#### Metrics +- `metric list` — List metrics +- `metric get` — Get metric details +- `metric create` — Create a custom metric +- `metric update` — Update a metric +- `metric delete` — Delete a metric +- `metric data` — Load metric data +- `metric dimension-values` — Get dimension values +- `metric drilldown` — Get drilldown data +- `metric usages` — See where a metric is used +- `metric verification` — View verification status +- `metric set-verification` — Toggle verification + +#### Activity Log +- `activity-log list` — List activity log entries + +#### Databoards +- `databoard list` — List databoards +- `databoard metrics` — View metrics on a databoard + +### Unchanged + +- `auth login` — Authentication flow unchanged +- `auth validate` — Key validation unchanged +- `analyze ask-genie` — Genie AI integration unchanged (uses separate agentic service) +- `--json` flag — Works the same on all commands +- Config file location — `~/.config/databox-cli/config.json` unchanged +- `DATABOX_API_KEY` / `DATABOX_API_URL` env vars — Work the same diff --git a/README.md b/README.md index b016d92..859da00 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # databox-cli -CLI for the [Databox](https://databox.com) public API. Manage accounts, data sources, datasets, push data, and analyze datasets with Genie AI — all from the terminal. +CLI for the [Databox](https://databox.com) V2 API. Manage accounts, data sources, datasets, metrics, connections, users, billing, and more — all from the terminal. ## Installation @@ -17,11 +17,21 @@ databox auth login # Verify your key works databox auth validate -# List your accounts -databox account list +# View your account +databox account info + +# List data sources +databox data-source list + +# Create a data source and dataset +databox data-source create --title "My Data Source" +databox dataset create --title "My Dataset" --data-source-id 12345 # Push data into a dataset -databox dataset ingest DATASET_ID --file data.json +databox dataset ingest 67890 --file data.json + +# List metrics +databox metric list ``` ## Authentication @@ -34,12 +44,34 @@ You can also pass the key inline: databox auth login --api-key YOUR_API_KEY ``` +## Global Flags + +| Flag | Env Var | Description | +|------|---------|-------------| +| `--json` | — | Output as JSON instead of table | +| `--api-key` | `DATABOX_API_KEY` | Override the stored API key | +| `--api-url` | `DATABOX_API_URL` | Override the API base URL | +| `--account-id` | `DATABOX_ACCOUNT_ID` | Target a specific account (for agency/client access) | + ## Output Formats By default, commands output human-readable tables. Add `--json` to any command for machine-readable JSON output: ```bash -databox account list --json +databox account info --json +databox data-source list --json +``` + +## Multi-Account Access + +For agency accounts managing client accounts, use the `--account-id` flag to scope commands to a specific client: + +```bash +# List your client accounts +databox client list + +# List data sources for a specific client +databox data-source list --account-id 12345 ``` ## Agent Skills @@ -51,9 +83,15 @@ This package includes shareable skills for AI agents (like [Claude Code](https:/ | Skill | Description | |-------|-------------| | `databox-auth` | Authentication setup and API key validation | -| `databox-accounts` | Account discovery, timezones, resource listing | -| `databox-data-sources` | Data source create, delete, and inspection | -| `databox-datasets` | Dataset CRUD, schema definition, data ingestion, monitoring | +| `databox-account` | Account info, usage, settings, timezones | +| `databox-data-sources` | Data source CRUD, timezone, sync, permissions, purge | +| `databox-datasets` | Dataset CRUD, schema, data ingestion, metadata, verification, modifications | +| `databox-metrics` | Metric CRUD, data loading, dimensions, drilldown, verification | +| `databox-users` | User invite, role management, removal | +| `databox-clients` | Client account management (agency model) | +| `databox-connections` | Connection management and permissions | +| `databox-integrations` | Browse available integration types | +| `databox-billing` | Billing info and invoices | | `databox-analyze` | Dataset analysis with Genie AI, conversational data Q&A | ### Install Skills @@ -68,116 +106,183 @@ Or install individual skills: ```bash npx skills add databox/databox-cli --skill databox-auth -npx skills add databox/databox-cli --skill databox-accounts +npx skills add databox/databox-cli --skill databox-account npx skills add databox/databox-cli --skill databox-data-sources npx skills add databox/databox-cli --skill databox-datasets +npx skills add databox/databox-cli --skill databox-metrics +npx skills add databox/databox-cli --skill databox-users +npx skills add databox/databox-cli --skill databox-clients +npx skills add databox/databox-cli --skill databox-connections +npx skills add databox/databox-cli --skill databox-integrations +npx skills add databox/databox-cli --skill databox-billing npx skills add databox/databox-cli --skill databox-analyze ``` -Once installed, Claude Code can manage your Databox resources directly — creating data sources, defining schemas, pushing data, monitoring ingestions, and analyzing datasets with Genie AI. +Once installed, Claude Code can manage your Databox resources directly — managing accounts, data sources, datasets, metrics, users, connections, billing, and analyzing data with Genie AI. ## Commands -* [`databox account data-sources ACCOUNTID`](#databox-account-data-sources-accountid) -* [`databox account datasets ACCOUNTID`](#databox-account-datasets-accountid) -* [`databox account list`](#databox-account-list) +* [`databox account data-sources`](#databox-account-data-sources) +* [`databox account datasets`](#databox-account-datasets) +* [`databox account info`](#databox-account-info) * [`databox account timezones`](#databox-account-timezones) +* [`databox account update`](#databox-account-update) +* [`databox account usage`](#databox-account-usage) +* [`databox activity-log list`](#databox-activity-log-list) * [`databox analyze ask-genie DATASETID QUESTION`](#databox-analyze-ask-genie-datasetid-question) * [`databox auth login`](#databox-auth-login) * [`databox auth validate`](#databox-auth-validate) +* [`databox billing info`](#databox-billing-info) +* [`databox billing invoices`](#databox-billing-invoices) +* [`databox client create`](#databox-client-create) +* [`databox client delete CLIENTID`](#databox-client-delete-clientid) +* [`databox client get CLIENTID`](#databox-client-get-clientid) +* [`databox client list`](#databox-client-list) +* [`databox client update CLIENTID`](#databox-client-update-clientid) +* [`databox connection delete CONNECTIONID`](#databox-connection-delete-connectionid) +* [`databox connection get CONNECTIONID`](#databox-connection-get-connectionid) +* [`databox connection list`](#databox-connection-list) +* [`databox connection permissions CONNECTIONID`](#databox-connection-permissions-connectionid) +* [`databox connection set-permissions CONNECTIONID`](#databox-connection-set-permissions-connectionid) +* [`databox connection update CONNECTIONID`](#databox-connection-update-connectionid) * [`databox data-source create`](#databox-data-source-create) * [`databox data-source datasets DATASOURCEID`](#databox-data-source-datasets-datasourceid) * [`databox data-source delete DATASOURCEID`](#databox-data-source-delete-datasourceid) +* [`databox data-source get DATASOURCEID`](#databox-data-source-get-datasourceid) +* [`databox data-source list`](#databox-data-source-list) +* [`databox data-source permissions DATASOURCEID`](#databox-data-source-permissions-datasourceid) +* [`databox data-source purge DATASOURCEID`](#databox-data-source-purge-datasourceid) +* [`databox data-source set-permissions DATASOURCEID`](#databox-data-source-set-permissions-datasourceid) +* [`databox data-source set-sync-frequency DATASOURCEID`](#databox-data-source-set-sync-frequency-datasourceid) +* [`databox data-source set-timezone DATASOURCEID`](#databox-data-source-set-timezone-datasourceid) +* [`databox data-source sync-frequencies DATASOURCEID`](#databox-data-source-sync-frequencies-datasourceid) +* [`databox data-source update DATASOURCEID`](#databox-data-source-update-datasourceid) +* [`databox databoard list`](#databox-databoard-list) +* [`databox databoard metrics DATABOARDID`](#databox-databoard-metrics-databoardid) +* [`databox dataset add-modification DATASETID`](#databox-dataset-add-modification-datasetid) +* [`databox dataset clear-modifications DATASETID`](#databox-dataset-clear-modifications-datasetid) +* [`databox dataset column-metadata DATASETID`](#databox-dataset-column-metadata-datasetid) * [`databox dataset create`](#databox-dataset-create) +* [`databox dataset data DATASETID`](#databox-dataset-data-datasetid) * [`databox dataset delete DATASETID`](#databox-dataset-delete-datasetid) +* [`databox dataset duplicate DATASETID`](#databox-dataset-duplicate-datasetid) * [`databox dataset get DATASETID`](#databox-dataset-get-datasetid) * [`databox dataset ingest DATASETID`](#databox-dataset-ingest-datasetid) * [`databox dataset ingestion DATASETID INGESTIONID`](#databox-dataset-ingestion-datasetid-ingestionid) +* [`databox dataset ingestion-statistics DATASETID`](#databox-dataset-ingestion-statistics-datasetid) * [`databox dataset ingestions DATASETID`](#databox-dataset-ingestions-datasetid) +* [`databox dataset list`](#databox-dataset-list) +* [`databox dataset metadata DATASETID`](#databox-dataset-metadata-datasetid) +* [`databox dataset modifications DATASETID`](#databox-dataset-modifications-datasetid) +* [`databox dataset permissions DATASETID`](#databox-dataset-permissions-datasetid) * [`databox dataset purge DATASETID`](#databox-dataset-purge-datasetid) +* [`databox dataset schema DATASETID`](#databox-dataset-schema-datasetid) +* [`databox dataset set-column-metadata DATASETID`](#databox-dataset-set-column-metadata-datasetid) +* [`databox dataset set-metadata DATASETID`](#databox-dataset-set-metadata-datasetid) +* [`databox dataset set-permissions DATASETID`](#databox-dataset-set-permissions-datasetid) +* [`databox dataset set-sync-frequency DATASETID`](#databox-dataset-set-sync-frequency-datasetid) +* [`databox dataset set-timezone DATASETID`](#databox-dataset-set-timezone-datasetid) +* [`databox dataset set-verification DATASETID`](#databox-dataset-set-verification-datasetid) +* [`databox dataset sync-frequencies DATASETID`](#databox-dataset-sync-frequencies-datasetid) +* [`databox dataset sync-history DATASETID`](#databox-dataset-sync-history-datasetid) +* [`databox dataset update DATASETID`](#databox-dataset-update-datasetid) +* [`databox dataset verification DATASETID`](#databox-dataset-verification-datasetid) * [`databox help [COMMAND]`](#databox-help-command) - -## `databox account data-sources ACCOUNTID` - -List data sources for a specific account +* [`databox integration get INTEGRATIONID`](#databox-integration-get-integrationid) +* [`databox integration list`](#databox-integration-list) +* [`databox metric create`](#databox-metric-create) +* [`databox metric data`](#databox-metric-data) +* [`databox metric delete METRICID`](#databox-metric-delete-metricid) +* [`databox metric dimension-values`](#databox-metric-dimension-values) +* [`databox metric drilldown`](#databox-metric-drilldown) +* [`databox metric get METRICID`](#databox-metric-get-metricid) +* [`databox metric list`](#databox-metric-list) +* [`databox metric set-verification METRICID`](#databox-metric-set-verification-metricid) +* [`databox metric update METRICID`](#databox-metric-update-metricid) +* [`databox metric usages METRICID`](#databox-metric-usages-metricid) +* [`databox metric verification METRICID`](#databox-metric-verification-metricid) +* [`databox profile info`](#databox-profile-info) +* [`databox profile update`](#databox-profile-update) +* [`databox user delete USERID`](#databox-user-delete-userid) +* [`databox user get USERID`](#databox-user-get-userid) +* [`databox user invite`](#databox-user-invite) +* [`databox user list`](#databox-user-list) +* [`databox user update USERID`](#databox-user-update-userid) + +## `databox account data-sources` + +List data sources for the current account ``` USAGE - $ databox account data-sources ACCOUNTID [--json] - -ARGUMENTS - ACCOUNTID The account ID to list data sources for + $ databox account data-sources [--json] [--page ] [--page-size ] FLAGS - --json Output as JSON + --json Output as JSON + --page= Page number (0-indexed) + --page-size= Number of items per page DESCRIPTION - List data sources for a specific account + List data sources for the current account EXAMPLES - $ databox account data-sources 12345 + $ databox account data-sources - $ databox account data-sources 12345 --json + $ databox account data-sources --page 0 --page-size 10 + + $ databox account data-sources --json ``` -_See code: [src/commands/account/data-sources.ts](https://github.com/databox/databox-cli/blob/v0.2.1/src/commands/account/data-sources.ts)_ +_See code: [src/commands/account/data-sources.ts](https://github.com/databox/databox-cli/blob/v1.0.0/src/commands/account/data-sources.ts)_ -## `databox account datasets ACCOUNTID` +## `databox account datasets` -List datasets for a specific account +List datasets for the current account ``` USAGE - $ databox account datasets ACCOUNTID [--json] [--page ] [--page-size ] [--type - datasets|merged_datasets] - -ARGUMENTS - ACCOUNTID The account ID to list datasets for + $ databox account datasets [--json] [--page ] [--page-size ] FLAGS --json Output as JSON - --page= Page number + --page= Page number (0-indexed) --page-size= Number of items per page - --type=