---
title: "exec"
description: "catcli exec — run one command against a data source of the project and print the result."
url: "https://docs.justcat.it/reference/cat-cli/exec/"
---
# exec


## Synopsis

```
catcli exec --dataSource <name> --command <text> [-p <path>] [-l <level>] [-q]
```

## Options

| Short | Long | Value | Meaning |
|-------|------|-------|---------|
| `-d` | `--dataSource` | name | Required. Name of a data source defined in the project. |
| `-c` | `--command` | text | Required. The command to run — SQL, DAX or whatever the data source's provider understands. Quote it. |
| `-p` | `--project` | path | Project file, or a directory with exactly one `*.cat.yaml`. Default: the current directory. |
| `-l` | `--loggingLevel` | level | `None` (default), `Error`, `Information`, `Debug`, … — see [Logging](https://docs.justcat.it/reference/cat-cli/introduction/#logging "Logging"). |
| `-q` | `--quiet` | | Hide the "working offline" notice. |

## What it does

Opens the project so that the data source — its provider, connection string, environment variables — is exactly what the tests use, sends the command through that provider, and prints what comes back. It is a troubleshooting tool: it answers *what does this query return through CAT, with this connection?* for data sources that have no query tool of their own (Excel and CSV files, for instance) and for checking a connection string without writing a test.

It is not a data export: the whole result is loaded and rendered as one table that has to fit the terminal. For more than a screenful of rows, use the PowerShell module's `Invoke-CatCommand`, which can write the result to a file.

## Output

The result set as a table — one column per result column, numbers and dates right-aligned, `NULL` shown as an empty cell — followed by the row count:

```
╭──────────┬───────────────┬───────────╮
│ GateCode │ Terminal      │ Capacity  │
├──────────┼───────────────┼───────────┤
│ A1       │ North         │       180 │
│ A2       │ North         │       180 │
╰──────────┴───────────────┴───────────╯

The command returned 2 rows.
```

When the provider reports an error, the error message is printed after the (empty) table:

```
!!! Error: Invalid object name 'DIM.GATE'.
```

## Exit code

`0` when the project opened and the command was sent — **also when the command itself failed**; the failure is reported in the output text only. `1` when the project could not be opened or the data source name does not exist. `2`–`7` from the sign-in and plan check — see [Exit codes](https://docs.justcat.it/reference/cat-cli/introduction/#exit-codes "Exit codes").

## Examples

```
# query a data source of the project in the current directory
catcli exec -d AERO_PROD -c "SELECT * FROM DIM.GATES"

# same, long names, explicit project
catcli exec --dataSource AERO_PROD --command "SELECT COUNT(*) FROM DIM.GATES" --project "D:\Testing\Aero.cat.yaml"

# the connection does not work? see what CAT does while it opens the project
catcli exec -d AERO_PROD -c "SELECT 1" -l Information
```

## Related

- [Introduction](https://docs.justcat.it/reference/cat-cli/introduction/ "Introduction") — conventions, sign-in, exit codes.
- [Data sources](https://docs.justcat.it/reference/data-sources/ "Data sources") and [Providers](https://docs.justcat.it/reference/data-sources/providers/ "Providers") — what each provider accepts as a command.
- [`show`](https://docs.justcat.it/reference/cat-cli/show/ "show") — the data-source names of the project are in its summary.