> ## Documentation Index
> Fetch the complete documentation index at: https://docs.elementary-data.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI install & configure

We recommend you install Elementary CLI using one of the following methods:

## Install Elementary CLI

The installation depends on the dbt version your project runs on.

### dbt v2 (Fusion)

Install the CLI without any extra:

```shell theme={null}
pip install elementary-data
```

Then install dbt v2 itself (the `dbt` or `dbt-oss` package) by following [dbt's installation guide](https://docs.getdbt.com/docs/local/install-dbt). dbt v2 has adapters built in, so no warehouse-specific package is needed.

### dbt Core 1.x

Install the CLI with the `dbt1-` extra matching your platform (no need to run all):

```shell theme={null}
pip install 'elementary-data[dbt1-snowflake]'
pip install 'elementary-data[dbt1-bigquery]'
pip install 'elementary-data[dbt1-redshift]'
pip install 'elementary-data[dbt1-databricks]'
pip install 'elementary-data[dbt1-athena]'
pip install 'elementary-data[dbt1-trino]'
pip install 'elementary-data[dbt1-clickhouse]'
pip install 'elementary-data[dbt1-duckdb]'
pip install 'elementary-data[dbt1-dremio]'
pip install 'elementary-data[dbt1-spark]'
pip install 'elementary-data[dbt1-postgres]'
```

The extra installs dbt Core 1.x and the warehouse adapter alongside the CLI. The legacy extras without the `dbt1-` prefix (e.g. `elementary-data[snowflake]`) are still supported and install the same packages.

For Vertica, install `elementary-data` and the `dbt-vertica` adapter directly:

```shell theme={null}
pip install elementary-data dbt-vertica
```

Run `edr --help` in order to ensure the installation was successful.

If you're receiving `command not found: edr` please check our [troubleshooting guide](https://docs.elementary-data.com/oss/general/troubleshooting.md).

## Install from source

Install Elementary directly from GitHub source:

```shell theme={null}
git clone https://github.com/elementary-data/elementary
pip install ./elementary
```

### Validate installation

To validate the installation and get usage instructions for the CLI run:

```shell theme={null}
edr --help
```

## CLI configuration

Elementary CLI requires a connection profile to connect to DWH. Additional configuration is made on `config.yml`:

* **Required:** `HOME_DIR/.dbt/profiles.yml` - Connection details to the data warehouse, in the format of dbt connection profile named `elementary`.
* **Optional:** `HOME_DIR/.edr/config.yml` - Elementary configuration.

(These default paths and names may be changed using the [CLI options](https://docs.elementary-data.com/oss/cli-commands.md#cli-advanced-options)).

> [accordion] How to create 'profiles.yml'?
>
> ## Configuring the Elementary Profile
>
> In order to connect, Elementary needs a [connection profile](https://docs.getdbt.com/dbt-cli/configure-your-profile) in a file named `profiles.yml`.
> This profile will be used by the CLI, to connect to the DWH and find the dbt package tables.
>
> The easiest way to generate the profile is to run the following command within the dbt project where you deployed the elementary dbt package (works in dbt cloud as well):
>
> ```shell theme={null}
> dbt run-operation elementary.generate_elementary_cli_profile
> ```
>
> > [!WARNING]
> >
> > Ensure that you fill in your password and any other missing fields after you
> > paste the profile in your **local** `profiles.yml` file.
>
> Copy the output, fill in the missing fields and add the profile to your `profiles.yml`.
> Here is a demonstration:
>
> [https://www.loom.com/embed/6eacaed618a746658a3c8e920d1d46b2](https://www.loom.com/embed/6eacaed618a746658a3c8e920d1d46b2)
>
> ### Elementary profile details and format
>
> * Path: `HOME_DIR/.dbt/profiles.yml`
> * Profile name: `elementary`
> * Schema name: The schema of elementary models, default is `<your_dbt_project_schema>_elementary`
>
> ```yml Snowflake theme={null}
> ## SNOWFLAKE ##
> ## By default, edr expects the profile name 'elementary'.      ##
> ## Configure the database and schema of elementary models.     ##
> ## Check where 'elementary_test_results' is to find it.        ##
>
> elementary:
>   outputs:
>     default:
>       type: snowflake
>       account: [account id]
>       user: [username]
>       role: [user role]
>
>       ## Keypair auth (recommended) ##
>       private_key_path: [path/to/private.key]
>       # or private_key instead of private_key_path
>       private_key_passphrase: [passphrase for the private key, if key is encrypted]
>
>       database: [database name]
>       warehouse: [warehouse name]
>       schema: [schema name]_elementary
>       threads: 4
> ```
>
> ```yml BigQuery theme={null}
> ## BIGQUERY ##
> ## By default, edr expects the profile name 'elementary'.      ##
> ## Configure the database and schema of elementary models.     ##
> ## Check where 'elementary_test_results' is to find it.        ##
>
> elementary:
>   outputs:
>     default:
>       type: bigquery
>
>       ## Service account auth ##
>       method: service-account
>       keyfile: [full path to your keyfile]
>
>       project: [project id]
>       dataset: [dataset name] # elementary dataset, usually [dataset name]_elementary
>       threads: 4
>       location: [dataset location]
>       priority: interactive
> ```
>
> ```yml Redshift theme={null}
> ## REDSHIFT ##
> ## By default, edr expects the profile name 'elementary'.      ##
> ## Configure the database and schema of elementary models.     ##
> ## Check where 'elementary_test_results' is to find it.        ##
>
> elementary:
>   outputs:
>     default:
>       type: redshift
>       host: [hostname, like hostname.region.redshift.amazonaws.com]
>
>       ## User/password auth ##
>       user: [username]
>       password: [password]
>
>       dbname: [database name]
>       schema: [schema name] # elementary schema, usually [schema name]_elementary
>       threads: 4
>       keepalives_idle: 240 # default 240 seconds
>       connect_timeout: 10 # default 10 seconds
>       # search_path: public # optional, not recommended
>       sslmode:
>         [
>           optional,
>           set the sslmode used to connect to the database (in case this parameter is set,
>           will look for ca in ~/.postgresql/root.crt),
>         ]
>       ra3_node: true # enables cross-database sources
> ```
>
> ```yml Databricks theme={null}
> ## DATABRICKS ##
> ## By default, edr expects the profile name 'elementary'.      ##
> ## Configure the database and schema of elementary models.     ##
> ## Check where 'elementary_test_results' is to find it.        ##
>
> elementary:
>   outputs:
>     default:
>       type: databricks
>       host: [hostname, like <ID>.cloud.databricks.com]
>       http_path: [like /sql/1.0/endpoints/<ID>]
>       schema: [schema name] # elementary schema, usually [schema name]_elementary
>       token: [token]
>       threads: [number of threads like 8]
> ```
>
> ```yml Postgres theme={null}
> ## POSTGRES ##
> ## By default, edr expects the profile name 'elementary'.      ##
> ## Configure the database and schema of elementary models.     ##
> ## Check where 'elementary_test_results' is to find it.        ##
>
> elementary:
>   outputs:
>     default:
>       type: postgres
>       host: [hostname]
>       user: [username]
>       password: [password]
>       port: [port]
>       dbname: [database name]
>       schema: [schema name] # elementary schema, usually [schema name]_elementary
>       threads: [1 or more]
>       keepalives_idle: 0 # default 0 seconds
>       connect_timeout: 10 # default 10 seconds
>       # search_path: public # optional, not recommended
>       # role: [optional, set the role dbt assumes when executing queries]
>       # sslmode: [optional, set the sslmode used to connect to the database]
> ```
>
> ```yml Athena theme={null}
> ## ATHENA ##
> ## By default, edr expects the profile name 'elementary'.      ##
> ## Configure the database and schema of elementary models.     ##
> ## Check where 'elementary_test_results' is to find it.        ##
>
> elementary:
>   outputs:
>     default:
>       type: athena
>       work_group: [athena workgroup]
>       s3_staging_dir: [s3_staging_dir] # Location to store query results & metadata
>       s3_data_dir: [s3 data dir] # Location to store table data (if not specified, s3_staging_dir is used)
>       region_name: [aws region name] # AWS region, e.g. eu-west-1
>       database: [database name]
>       schema: [schema name] # elementary schema, usually [schema name]_elementary
>       threads: [number of threads like 8]
> ```
>
> ```yml Clickhouse theme={null}
> ## Clickhouse ##
> ## By default, edr expects the profile name 'elementary'.      ##
> ## Configure the database and schema of elementary models.     ##
> ## Check where 'elementary_test_results' is to find it.        ##
>
> elementary:
>   outputs:
>     default:
>       type: clickhouse
>       schema: [schema name] # elementary schema, usually [schema name]_elementary
>       host: [hostname]
>       port: [port]
>       user: [username]
>       password: [password]
>       threads: [number of threads like 8]
> ```
>
> ```yml Trino theme={null}
> ## Trino ##
> ## By default, edr expects the profile name 'elementary'.      ##
> ## Configure the database and schema of elementary models.     ##
> ## Check where 'elementary_test_results' is to find it.        ##
>
> elementary:
>   outputs:
>     default:
>       type: trino
>       host: [hostname]
>       port: [port]
>       database: [database name]
>       schema: [schema name] # elementary schema, usually [schema name]_elementary
>       threads: [1 or more]
>       method: [authentication method] # ldap, oauth etc.
>       user: [username]
>       # password: [optional, used with ldap authentication ]
>       # session_properties: [optional, sets Trino session properties used in the connection]
> ```
>
> ```yml DuckDB theme={null}
> ## DUCKDB ##
> ## By default, edr expects the profile name 'elementary'.      ##
> ## Configure the database and schema of elementary models.     ##
> ## Check where 'elementary_test_results' is to find it.        ##
>
> elementary:
>   outputs:
>     default:
>       type: duckdb
>       path: [path to your .duckdb file]
>       schema: [schema name] # elementary schema, usually [schema name]_elementary
>       threads: [1 or more]
> ```
>
> ```yml Dremio theme={null}
> ## DREMIO ##
> ## By default, edr expects the profile name 'elementary'.      ##
> ## Configure the database and schema of elementary models.     ##
> ## Check where 'elementary_test_results' is to find it.        ##
>
> ## -- Dremio Cloud -- ##
> elementary:
>   outputs:
>     default:
>       type: dremio
>       cloud_host: api.dremio.cloud  # or api.eu.dremio.cloud for EU
>       cloud_project_id: [project ID]
>       user: [email address]
>       pat: [personal access token]
>       use_ssl: true
>       object_storage_source: [name]  # alias: datalake
>       object_storage_path: [path]    # alias: root_path
>       dremio_space: [name]           # alias: database
>       dremio_space_folder: [path]    # alias: schema, usually [schema]_elementary
>       threads: [1 or more]
>
> ## -- Dremio Software -- ##
> elementary:
>   outputs:
>     default:
>       type: dremio
>       software_host: [hostname or IP address]
>       port: 9047
>       user: [username]
>       password: [password]  # or use pat: [personal access token]
>       use_ssl: [true or false]
>       object_storage_source: [name]  # alias: datalake
>       object_storage_path: [path]    # alias: root_path
>       dremio_space: [name]           # alias: database
>       dremio_space_folder: [path]    # alias: schema, usually [schema]_elementary
>       threads: [1 or more]
> ```
>
> ```yml Spark theme={null}
> ## SPARK ##
> ## By default, edr expects the profile name 'elementary'.      ##
> ## Configure the database and schema of elementary models.     ##
> ## Check where 'elementary_test_results' is to find it.        ##
>
> elementary:
>   outputs:
>     default:
>       type: spark
>       method: [thrift, http, or odbc]
>       host: [hostname]
>       port: [port]
>       user: [username]
>       schema: [schema name] # elementary schema, usually [schema name]_elementary
>       threads: [1 or more]
>       # token: [optional, used with http method]
> ```
>
> ```yml Fabric theme={null}
> ## FABRIC ##
> ## By default, edr expects the profile name 'elementary'.      ##
> ## Configure the database and schema of elementary models.     ##
> ## Check where 'elementary_test_results' is to find it.        ##
>
> elementary:
>   outputs:
>     default:
>       type: fabric
>       driver: ODBC Driver 18 for SQL Server
>       server: [hostname]
>       port: 1433
>       database: [database name]
>       schema: [schema name] # elementary schema, usually [schema name]_elementary
>       authentication: ActiveDirectoryServicePrincipal
>       tenant_id: [tenant_id]
>       client_id: [client_id]
>       client_secret: [client_secret]
>       threads: [1 or more]
> ```
>
> ```yml SQL Server theme={null}
> ## SQL SERVER ##
> ## By default, edr expects the profile name 'elementary'.      ##
> ## Configure the database and schema of elementary models.     ##
> ## Check where 'elementary_test_results' is to find it.        ##
>
> elementary:
>   outputs:
>     default:
>       type: sqlserver
>       driver: ODBC Driver 18 for SQL Server
>       server: [hostname]
>       port: 1433
>       database: [database name]
>       schema: [schema name] # elementary schema, usually [schema name]_elementary
>       user: [username]
>       password: [password]
>       threads: [1 or more]
>       # encrypt: true # default true in dbt-sqlserver >= 1.2.0
>       # trust_cert: false
> ```
>
> ```yml Vertica theme={null}
> ## VERTICA ##
> ## By default, edr expects the profile name 'elementary'.      ##
> ## Configure the database and schema of elementary models.     ##
> ## Check where 'elementary_test_results' is to find it.        ##
>
> elementary:
>   outputs:
>     default:
>       type: vertica
>       host: [hostname]
>       port: 5433
>       database: [database name]
>       schema: [schema name] # elementary schema, usually [schema name]_elementary
>       username: [username]
>       password: [password]
>       threads: [1 or more]
>       # connection_load_balance: true
>       # backup_server_node: [comma separated list of backup hostnames or IPs]
> ```

> [accordion] dbt-core user? You already have profiles.yml
>
> If you are a dbt user, you already have a `profiles.yml` file that you can use. The default path of the dbt profiles file is `~/.dbt/` directory.
>
> * For further details, please refer to [dbt's documentation](https://docs.getdbt.com/reference/profiles.yml) about the file.
> * Note: in BigQuery we require 'location' ([details](https://cloud.google.com/bigquery/docs/locations)), and in dbt it is optional.

> [accordion] What is a connection profile?
>
> Elementary requires connection details and credentials to connect to the data warehouse.
>
> These are configured in a connection profile using a file named `profiles.yml`.
>
> **We recommend creating a dedicated database, or at least a schema.**
>
> Elementary leverages dbt's [connection profile](https://docs.getdbt.com/dbt-cli/configure-your-profile) format.
>
> **dbt-core users**
> Just add a profile with the relevant details, and name it `elementary`.

> [accordion] What permissions are required for the elementary profile?
>
> The provided credentials need to have permission to:
>
> * Read - Information schema and the tables configured for monitoring.,
> * Write - To the database configured in `elementary` profile, including creating new schemas.

> [accordion] How to create 'config.yml'?
>
> Only create this file if you need to use it for configuration, it is not mandatory.\
> Create a new directory and yml file under: HOME\_DIR/.edr/config.yml
>
> Here is the format of the yml itself:
>
> ```yml config.yml theme={null}
> # alerts destination #
> slack:
>   notification_webhook: <your_slack_webhook_url>
>   # optional #
>   workflows: false
> ```

> [accordion] Anonymous tracking
>
> We want to keep building and improving, and for that, we need to understand how users work with Elementary (and data is fun!). For that we added an anonymous tracking of events using [Posthog](https://posthog.com/) (open-source product analytics, highly recommended).
>
> We only track start, end, platform, number of queries and the size of the graph. No credentials, queries content, table names or anything private (not now and not ever).
>
> By default this completely anonymous tracking is turned on. You can opt-out at any time by adding the following to your `config.yml` file:
>
> ```shell theme={null}
> anonymous_usage_tracking: False
> ```

***

> [accordion] Have a question?
>
> We are available on [Slack](https://elementary-data.com/community), reach out for any kind of help!


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.