databox-data-sources

Files (1)

• SKILL.md

SKILL.md (first lines)

# Databox Data Source Management

Full data source lifecycle — list, create, configure, and delete — via the `databox` CLI.

## Prerequisites

Must be authenticated. If not, use the `databox-auth` skill first.

## Required Role

The API applies the Databox app's role rules, checked in the organization or account that owns the data source:

- Reads (`list`, `get`, `permissions`, `datasets`, `sync-frequency-options`): anyone with access.
- `create`, `update`, `set-sync-frequency`: Admin, User or Editor. A Viewer can only read.
- `delete`, `purge`, `set-timezone` (with or without `--purge-data`), `set-permissions`, and `dataset create` on this data source: an admin, or the user who created the data source.

A refusal is `forbidden` (exit 1) and nothing is changed. Do not retry it: tell the user which role the command needs, so an admin or the creator can run it.

## Quick Reference

| Task | Command |
|------|---------|
| List data sources | `databox data-source list` |
| Search data sources | `databox data-source list --search "analytics"` |
| Get data source details | `databox data-source get ID` |
| Create data source | `databox data-source create --name "Name"` |
| Create with key | `databox data-source create --name "Name" --integration-key Datadoo` |
| Update name | `databox data-source update ID --name "New Name"` |
| Set timezone | `databox data-source set-timezone ID --timezone "US/Eastern"` |
| Set timezone for its datasets too | `databox data-source set-timezone ID --timezone "US/Eastern" --apply-to-datasets` |
| View sync frequency options | `databox data-source sync-frequency-options ID` |
| Set sync frequency | `databox data-source set-sync-frequency ID --interval 60` |
| View permissions | `databox data-source permissions ID` |
| Set permissions | `databox data-source set-permissions ID --access-level everyone` |
| Restrict to some users | `databox data-source set-permissions ID --access-level selectedUsers --access-list 31 --access-list 42` |
| List linked datasets | `databox data-source datasets ID` |
| Purge all data | `databox data-source purge ID --force` |
| Delete data source | `databox data-source delete ID --force` |

## Common Workflow: Set Up a New Data Source

```bash
# 1. Create a data source
databox data-source create --name "My API Data" --timezone "UTC" --json
# Returns: {"id": 42, ...}

# 2. Create a dataset under it
databox dataset create --name "Daily Metrics" --data-source-id 42

# 3. Push data
databox dataset ingest 67890 --file data.json
```

## Sync Frequency

`--interval` is in minutes: `1`, `15`, `60`, `240`, `360`, `480` or `1440`. Run `data-source sync-frequency-options ID` first to see which intervals the data source can use and which your plan includes. `set-sync-frequency` and `set-timezone` print a confirmation; with `--json` they print the updated data source.

## Permissions

`--access-level` is `everyone`, `selectedUsers` or `private`. `--access-list USER_ID` (repeatable) is only accepted with `selectedUsers`, and each ID must be a user of the organization or already on the list; any other is rejected with `invalid_input` naming it, and nothing changes. Admins and the organization owner always keep access.

## Destructive Operations

These commands prompt for confirmation at a terminal. Off a terminal (scripts, agents) they read the answer from stdin instead, and when nothing is piped they exit 2 without doing anything. Agents should always pass `--force`:
- `data-source delete` — removes the data source entirely
- `data-source purge` — removes all data but keeps the data source

## Notes

- All commands support `--json` for machine-readable output
- Data source IDs are numeric (e.g., `42`). Find one with `databox data-source list`; in the Databox app it is the number in the Data Manager page URL (`/data-manager/connected/42/datasets/view`). A data source ID is not a dataset ID: list its datasets with `databox data-source datasets 42`.
- The `--integration-key` flag on create sets the integration key for third-party integrations (e.g., Datadoo)

From databox/databox-cli, MIT.

More from databox/databox-cli