Manage Databox using the CLI

Availability

Admins

All accounts

Development workflows rarely stay in the browser. Teams managing data pipelines, CI/CD processes, or scripted automation need to interact with Databox without switching context. The Databox CLI brings the full platform into your terminal — letting you create data sources, ingest records, query datasets with AI, and manage accounts alongside the rest of your developer tooling. It also ships with installable agent skills, so AI coding assistants like Claude Code can manage your Databox account autonomously.

Install the CLI

The Databox CLI requires Node.js 18 or higher. Install it globally via npm:

npm install -g databox-cli

To verify the installation:

databox --version

Authenticate

All CLI commands authenticate using a Databox API key. The key is stored locally at ~/.config/databox-cli/config.json and sent as an x-api-key header over HTTPS.

Generate an API key in your Databox account. Follow the steps on the Authentication page in the Databox API documentation.
Run the login command:

databox auth login

You'll be prompted to enter your API key interactively. To pass it inline instead:

databox auth login --api-key YOUR_API_KEY

Validate that the key is stored correctly:

databox auth validate

Note: API keys are scoped to your account permissions. Commands that require higher access levels will fail if the key belongs to a user without the appropriate role.

Manage accounts

Use account commands to explore what's available in your Databox account before creating or ingesting data.

View accessible accounts:

databox account list

List data sources in an account:

databox account data-sources ACCOUNTID

List datasets in an account:

databox account datasets ACCOUNTID

Supports optional flags for filtering by type and paginating large result sets.

View supported time zones:

databox account timezones

Manage data sources

A data source is a logical container for one or more datasets. Create ]one before defining your dataset structure.

Create a data source:

databox data-source create --title "Production Metrics"

Supports optional --timezone and key flags. Use databox account timezones to see valid timezone values.

List datasets under a data source:

databox data-source datasets DATASOURCEID

Delete a data source:

databox data-source delete DATASOURCEID

Warning: Deleting a data source is irreversible and removes all associated datasets and their data. Use --force to skip the confirmation prompt in automated scripts.

Manage datasets

Datasets are structured tables that hold your records. Define the schema and primary keys at creation time — these determine how incoming records are validated and how duplicates are handled.

Create a dataset:

databox dataset create --data-source-id DATASOURCEID --title "Daily Revenue"

Supports optional schema definitions and primary key flags.

Retrieve dataset details:

databox dataset get DATASETID

Ingest records into a dataset:

databox dataset ingest DATASETID --file ./records.json

Accepts data from a file path, inline JSON, or piped stdin — making it easy to wire into existing scripts and pipelines:

cat records.json | databox dataset ingest DATASETID

View ingestion history:

databox dataset ingestions DATASETID

Inspect a specific ingestion:

databox dataset ingestion DATASETID INGESTIONID

Purge all data from a dataset (keep the schema):

databox dataset purge DATASETID

Delete a dataset entirely:

databox dataset delete DATASETID

Warning: Purge and delete are irreversible. Both require explicit --force or interactive confirmation.

Analyze data with Genie

Genie lets you query any dataset using natural language from the terminal. Answers are computed by Databox's analytics engine — not generated by an LLM — so the results reflect your actual data.

Ask a question:

databox analyze ask-genie DATASETID "What was the total revenue last month?"

Responses stream in real time. To continue a conversation, pass the thread ID returned by the first response:

databox analyze ask-genie DATASETID "How does that compare to the month before?" --thread THREADID

Use the CLI with AI agents

The CLI ships with five modular agent skills covering authentication, accounts, data sources, datasets, and analysis. Install them via:

npx skills add databox/databox-cli

Once installed, AI coding assistants — including Claude Code and Cursor — can autonomously manage your Databox account: creating data sources, ingesting records, querying datasets, and more.

Output formats

Every command returns human-readable formatted tables by default. Add --json to any command for machine-readable output suitable for scripts, pipelines, or downstream processing:

databox account list --json

Command reference

Command	Description
`databox auth login`	Authenticate with your API key
`databox auth validate`	Validate the stored API key
`databox account data-sources ACCOUNTID`	List data sources in an account
`databox account datasets ACCOUNTID`	List datasets in an account
`databox account list`	List accessible accounts
`databox account timezones`	List supported time zones
`databox analyze ask-genie DATASETID QUESTION`	Query a dataset using natural language
`databox data-source create --title <value>`	Create a new data source
`databox data-source datasets DATASOURCEID`	List datasets under a data source
`databox data-source delete DATASOURCEID`	Delete a data source
`databox dataset create --data-source-id <value> --title <value>`	Create a new dataset
`databox dataset delete DATASETID`	Delete a dataset
`databox dataset get DATASETID`	Retrieve dataset details
`databox dataset ingest DATASETID`	Ingest records via file, JSON, or stdin
`databox dataset ingestion DATASETID INGESTIONID`	Inspect a specific ingestion
`databox dataset ingestions DATASETID`	List ingestion history for a dataset
`databox dataset purge DATASETID`	Clear all data from a dataset

FAQ

Can I use the CLI in CI/CD pipelines and automated scripts?

Yes. Every command supports the --json flag for machine-readable output, and destructive commands accept --force to skip interactive confirmation prompts — making the CLI suitable for fully automated environments.

Does the CLI work on Windows?

Yes. The CLI is an npm package and runs on any platform where Node.js 18+ is supported, including Windows, macOS, and Linux.

How do I update the CLI?

Run npm update -g databox-cli to install the latest version. Because all business logic runs on Databox's servers, most new features and improvements do not require a client update.

Is my API key stored securely?

The key is stored in a local config file at ~/.config/databox-cli/config.json. It is transmitted only as an HTTPS header to Databox's servers. Treat this file like any other credential — avoid committing it to version control.

What happens if I ingest duplicate records?

Duplicate handling depends on the primary keys defined when the dataset was created. Records matching an existing primary key overwrite the existing entry; records with unique primary keys are appended as new rows.