Academy
CLI and MCP

Dattos CLI: installation and first steps

Dattos CLI: installation and first steps

The Dattos CLI is the platform’s command-line interface — designed to operate Dattos through scripts, automation pipelines, and artificial intelligence agents. All output is in JSON (easy to process in any language or with jq), errors are returned in a structured format with guidance for correction, and the same installation also includes the Python SDK and the MCP server for artificial intelligence assistants.

When the CLI is the right choice. When the steps are already known and need to be repeated identically: scheduled execution, automation pipelines, or replicating a process across environments. JSON output and exit codes (0 success, 1 API error, 2 authentication or configuration error) allow the script to stop on its own at the exact point where something failed. If the path depends on what is found — investigating why a reconciliation did not match, for example — or if the operator is not technical, MCP is a better fit: see "Connect artificial intelligence assistants via MCP".

Requirements and installation

  • Dattos 16.4 or later. This is the minimum platform version; dattos doctor confirms your instance version.

  • Python 3.11 or later, on any operating system.

  • Install with pip:

pip install dattos

  • Verify the installation:

dattos version

The installation provides three commands: dattos (the CLI), dattos-mcp (MCP server for artificial intelligence assistants), and dattos-mcp-http (server variant for hosted use).

Will you use the local MCP server? Install with the extras: pip install "dattos[mcp,security]". Without them, the dattos-mcp command is installed but does not start. To connect cloud-based assistants, none of this is necessary — see "Connect artificial intelligence assistants via MCP".

Generate your API key

Go to My Profile > API Keys, create a new key, and copy the generated value — it starts with api-. The key is displayed only once.

The key carries the permissions of the user who generated it: folders, screens, and approval levels follow that user’s privacy profile. Revoking the key on the same screen cuts off access for any integration using it, and the operation cannot be undone.

Store the key in environment variables

This is the recommended standard. The key is not stored in a project file, does not appear in the terminal history, and cannot accidentally be committed to version control. It is also the mechanism already used by automation servers and containers.

There are four variables, two of them required:

  • DATTOS_API_URL — required. The complete address: https://sua-empresa.dattos.com.br/dattos.api.

  • DATTOS_API_KEY — required. The key you just generated.

  • DATTOS_FOLDER_ID — optional. The default folder for all commands.

  • DATTOS_PROFILE — optional. The active profile.

Environment variables take precedence over any other CLI configuration. In other words, they always win.

The instructions below save the variables permanently for your machine user — configure them once and they will apply forever, in any terminal you open afterward.

On Windows — through the interface (simplest)

  1. Open Start and type edit environment variables.

  2. Click Edit environment variables for your account. (This option applies to your user and does not require an administrator password.)

  3. In the upper section, User variables, click New....

  4. Under Variable name, enter DATTOS_API_URL. Under Variable value, paste https://sua-empresa.dattos.com.br/dattos.api. Click OK.

  5. Click New... again. This time, under Variable name, enter DATTOS_API_KEY, and under Variable value, paste your key (api-...). Click OK.

  6. Click OK to close the remaining windows.

On Windows — through PowerShell (alternative)

If you prefer the command line, open PowerShell and run the two commands, replacing the values with yours:

[Environment]::SetEnvironmentVariable("DATTOS_API_URL", "https://sua-empresa.dattos.com.br/dattos.api", "User")
[Environment]::SetEnvironmentVariable("DATTOS_API_KEY", "api-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "User")

On Linux and macOS

Add the two lines to your terminal’s startup file — ~/.bashrc if you use bash, or ~/.zshrc if you use zsh (the default on macOS). Open Terminal and run:

echo 'export DATTOS_API_URL="https://sua-empresa.dattos.com.br/dattos.api"' >> ~/.bashrc
echo 'export DATTOS_API_KEY="api-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"' >> ~/.bashrc
source ~/.bashrc

Check whether it worked

On Windows: open Start, type cmd, and open Command Prompt. Enter the command below and press Enter:

echo %DATTOS_API_KEY%

On Linux or macOS: open Terminal, enter the command below, and press Enter:

echo "$DATTOS_API_KEY"

In both cases, your key should appear on the screen. If the command text itself appears (or nothing appears), the variable was not saved — repeat the steps.

Open a new terminal. Terminal windows that were already open before you saved the variables do not receive the values. Close and reopen one before testing.

In automations (Jenkins, GitHub Actions, Azure DevOps), store the key in the tool’s own secrets vault and inject it as an environment variable. Never write the key in the pipeline file. If you use a .env file inside a project, add it to .gitignore before writing the key to it.

Other authentication methods

All the options below depend on the operating system’s credential store (Windows Credential Manager, macOS Keychain, or Secret Service on Linux), which requires installation with the [security] extra:

pip install "dattos[security]"

  • Save to the CLI configuration — dattos config set api-url "sua-empresa" and dattos config set api-key "api-...". For api-url, only the instance name is needed: the CLI completes it with the full address.

  • Interactive login — dattos auth login authenticates with a username and password and generates a session token. dattos auth login --browser opens the API keys page in your browser so you can create and paste the key.

  • Check and clear — dattos auth status shows the active method; dattos auth logout removes the credentials.

Without the credential store available, these options do not behave as expected. On a server without a graphical session, or if the [security] extra is not installed: dattos config set api-key saves the key in plain text in the ~/.dattos/config.json file, and dattos auth login reports success without storing the credential. To confirm that the key was saved to the credential store, check whether the config set response contains "storage": "keyring". On servers and in automations, use environment variables — this is the recommended approach precisely because it does not depend on the credential store.

Basic concepts

  • Folders: many operations run in the context of an execution folder. Select one with dattos folders select (interactive list) and check it with dattos folders current.

  • Profiles: for those working with more than one instance or environment, dattos config profile list and dattos config profile switch <nome> switch between complete configurations.

  • Output and errors: results are returned as JSON on stdout; errors as JSON on stderr, with the next_step field indicating the command that resolves the issue and correlation_id for contacting support. Exit codes: 0 success, 1 API error, 2 authentication or configuration error — ready for flow control in scripts.

  • Diagnostics: dattos doctor validates configuration, connectivity, authentication, instance version, and active folder all at once. With --deep, it also tests the platform’s artificial intelligence services. It is the first command to run when something does not work.

  • Status glossary: dattos status-glossary explains any status returned by the platform. Use it before interpreting a status in a script.

First complete workflow

Create a reconciliation with the assistance of Dattos AI and run it directly from the terminal:

dattos folders select 2473
dattos etl create --name "Conciliação Vendas"
dattos etl add-source --etl 891 --file vendas.xlsx
dattos etl add-source --etl 891 --file extrato.csv
dattos etl pipeline create "Conciliar vendas com extrato por valor e data" --etl 891
dattos etl start 891 --date 2026-06-30 --wait

The order matters: the etl pipeline create command requires at least one data source to have already been added. If called earlier, it tells you exactly which step is missing.

And check the result:

dattos etl execution-status 891 --date 2026-06-30
dattos matching status 891 <loadId> <matchingId>
dattos reports generate 891 --load-id <loadId> --dataset-id <datasetId> --format xlsx

The complete command catalog is available in the article "Dattos CLI: commands and capabilities".

Was this helpful?
Was this helpful?