# Manage Databox using the CLI 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: ```bash npm install -g databox-cli ``` To verify the installation: ```bash 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. 1. Generate an API key in your Databox account. Follow the steps on the [Authentication page](https://developers.databox.com/docs/api/authentication) in the Databox API documentation. 2. Run the login command: ```bash databox auth login ``` You'll be prompted to enter your API key interactively. To pass it inline instead: ```bash databox auth login --api-key YOUR_API_KEY ``` 1. Validate that the key is stored correctly: ```bash databox auth validate ``` 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:** ```bash databox account list ``` **List data sources in an account:** ```bash databox account data-sources ACCOUNTID ``` **List datasets in an account:** ```bash databox account datasets ACCOUNTID ``` Supports optional flags for filtering by type and paginating large result sets. **View supported time zones:** ```bash databox account timezones ``` ## Manage data sources A [data source](/add-a-data-source) is a logical container for one or more datasets. Create ]one before defining your dataset structure. **Create a data source:** ```bash 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:** ```bash databox data-source datasets DATASOURCEID ``` **Delete a data source:** ```bash databox data-source delete DATASOURCEID ``` 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](/understanding-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:** ```bash databox dataset create --data-source-id DATASOURCEID --title "Daily Revenue" ``` Supports optional schema definitions and primary key flags. **Retrieve dataset details:** ```bash databox dataset get DATASETID ``` **Ingest records into a dataset:** ```bash 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: ```bash cat records.json | databox dataset ingest DATASETID ``` **View ingestion history:** ```bash databox dataset ingestions DATASETID ``` **Inspect a specific ingestion:** ```bash databox dataset ingestion DATASETID INGESTIONID ``` **Purge all data from a dataset (keep the schema):** ```bash databox dataset purge DATASETID ``` **Delete a dataset entirely:** ```bash databox dataset delete DATASETID ``` Purge and delete are irreversible. Both require explicit `--force` or interactive confirmation. ## Analyze data with Genie [Genie](/get-started-with-genie-the-databox-ai-assistant) 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:** ```bash 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: ```bash 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: ```bash 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: ```bash 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 ` | 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 --title ` | 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 | 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. Yes. The CLI is an npm package and runs on any platform where Node.js 18+ is supported, including Windows, macOS, and Linux. 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. 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. 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.   Ask Genie Get instant answers or help with your data using the in-app AI assistant. Talk to an expert For customers: Get help with your setup, strategy, or making the most of Databox. Book a demo New to Databox? See how it works and get guidance on getting started. Send an email Reach out to support for help with your account, data, or technical issues.