CLI Overview

The DataRecs CLI (datarecs) lets you manage workspaces, connections, jobs, runs, webhooks, SSO, encryption, storage, and more from your terminal.

Installation

The CLI is published as @datarecs/cli on the DataRecs package registry. Configure your npm client for that registry (per your onboarding instructions), then:

npm install -g @datarecs/cli

Authentication

datarecs auth login --company your-company-slug

auth login uses the OAuth device flow — it prints a code and a URL to complete in your browser. The company (tenant) slug is required (pass --company/-c, set DATARECS_TENANT, or let the CLI prompt) so the platform can route you to the right cell.

Your access token is stored securely in your operating system’s keychain (not in a plaintext file).

For non-interactive/CI use, set DATARECS_API_KEY to a tenant API key (format dtrcs:<tenant_id>:<key_id>:<secret>) — this skips the device-code flow entirely and also switches output to JSON automatically (detected as a CI/scripted context), even without --json.

Configuration

Non-secret settings live in ~/.datarecs/config.json. Set a value:

datarecs config set apiUrl https://api.datarecs.io

Valid keys are apiUrl, outputFormat, and namespace. View the current config:

datarecs config view

Command structure

datarecs <topic> <action> [options]

Common topics (run datarecs <topic> --help for actions and flags):

Topic	What it manages
auth	Login, token refresh
config	Local CLI configuration
workspaces	Workspaces
connections	Data source connections (and connections reservations)
jobs	Reconciliation jobs, plus jobs runs and jobs schedules
job-groups	Grouping of related jobs
webhooks	Webhook endpoints, subscriptions, deliveries, secrets, test events
encryption	Bring-your-own-key (BYOK) configuration & migration
storage	Bring-your-own-storage (BYOS) configuration & migration
sso	SSO / SCIM connectors
connectors	OIDC connectors
email-recipient-rules, settings	Email notification routing & settings
audit-log, users	Audit log access, users me

Output defaults to a table; pass --json for machine-readable output.

Run datarecs --help or datarecs <topic> --help for full usage details. Note that resource topics are plural (workspaces, connections, jobs), and there is no api-key topic — API keys are managed in the Console, via the REST API, or with Terraform.

datarecs --help groups topics into readable sections — Reconciliation resources, Authentication & identity, Tenant configuration, Webhooks, Audit, Support, and CLI setup & tools — instead of one long alphabetical list.

Connect an AI assistant (MCP)

The CLI can serve DataRecs to AI tools over the Model Context Protocol:

datarecs mcp serve

This runs a local MCP server with the full read/write tool set. For the hosted connector and connection examples for Claude Code, Claude Desktop, and Cursor, see Connect DataRecs to AI tools (MCP).

Anonymous usage analytics (opt-in)

The CLI can send anonymous usage analytics to help us improve it. It is opt-in and off by default — nothing is sent unless you turn it on, and it never includes your company slug, resource ids, credentials, command arguments, or flag values.

datarecs config telemetry            # show the current state
datarecs config telemetry enable     # opt in
datarecs config telemetry disable    # opt out

On a first interactive run the CLI asks once. Automated environments never send or prompt: telemetry stays off in CI, in non-interactive sessions, and whenever DO_NOT_TRACK is set.