Skip to main content

Install Fusion from the CLI Preview

Fusion can be installed via the command line from our official content delivery network (CDN). Fusion CLI delivers dbt Fusion Engine performance benefits (faster parsing, compilation, execution) but does not include LSP features. For the best dbt Fusion Engine experience, install the dbt VS Code extension in your VS Code or compatible IDE.

If you already have the dbt Fusion Engine installed, you can skip this step. If you don't have it installed, you can follow these steps to install it:

  1. Open a new command-line window and run the following command to install the dbt Fusion Engine:

    Run the following command in the terminal:

    curl -fsSL https://public.cdn.getdbt.com/fs/install/install.sh | sh -s -- --update

    To use dbtf immediately after installation, reload your shell so that the new $PATH is recognized:

    exec $SHELL

    Or, close and reopen your Terminal window. This will load the updated environment settings into the new session.

  2. Run the following command to verify you've installed Fusion:

    dbtf --version

    You can use dbt or its Fusion alias dbtf (handy if you already have another dbt CLI installed). Default install path:

    • macOS/Linux: $HOME/.local/bin/dbt
    • Windows: C:\Users\<username>\.local\bin\dbt.exe

    The installer adds this path automatically, but you may need to reload your shell for the dbtf command to work.

Update Fusion​

The following command will update to the latest version of Fusion and adapter code:

dbtf system update

Uninstall Fusion​

This command will uninstall the Fusion binary from your system, but aliases will remain wherever they are installed (for example ~/.zshrc):

dbtf system uninstall

Adapter installation​

The Fusion install automatically includes adapters outlined in the Fusion requirements. Other adapters will be available at a later date.

Environment variables​

Fusion automatically loads environment variables from a .env file in your current working directory (the folder you cd into and run dbt commands from in your terminal). This helps you manage credentials and settings without hardcoding them in your profiles.yml or exposing them in your shell history.

Using a .env file​

  1. Create a .env file in your current working directory (typically at the root of your dbt project):

    DBT_MY_DATABASE=my_database
    DBT_MY_SCHEMA=my_schema
    DBT_SECRET_KEY=my_secret_value

  2. Reference these variables in your profiles.yml using the env_var Jinja function:

    my_profile:
      target: dev
      outputs:
        dev:
          type: snowflake
          account: my_account
          database: "{{ env_var('DBT_MY_DATABASE') }}"
          schema: "{{ env_var('DBT_MY_SCHEMA') }}"

  3. Run dbt commands normally. Fusion will automatically load the variables from the .env file. For example, running dbtf debug will show your connection using the values from .env:

    dbtf debug
    ...
    Debugging connection:
    "authenticator": "my_authenticator",
    "account": "my_account",
    "user": "my_user",
    "database": "my_database",        # Loaded from DBT_MY_DATABASE in .env
    "schema": "my_schema",            # Loaded from DBT_MY_SCHEMA in .env
note

We recommend placing your .env file in the project root and running dbt commands from that location because the file is loaded only from your current working directory. It doesn't support the --project-dir flag or DBT_PROJECT_DIR environment variable, and dbt won't search your project root if you're running commands from a different directory location.

Precedence order​

When the same environment variable is defined in multiple places, Fusion uses the following precedence order (highest to lowest):

  1. Shell environment — Variables set directly in your shell (for example, export DBT_MY_VAR=value)
  2. .env file — Variables defined in the .env file in your current working directory

This means environment variables set in your shell always override values from the .env file.

tip

Add .env to your .gitignore file to prevent sensitive credentials from being committed to version control. The dbtf init command automatically includes .env in the generated .gitignore file.

For more details on managing environment variables locally, refer to Configure your local environment.

profiles.yml location​

Fusion searches for profiles.yml in the --profiles-dir flag (if specified), project root directory, or ~/.dbt/ directory. Unlike dbt Core, Fusion does not support the DBT_PROFILES_DIR environment variable or profiles.yml in arbitrary working directories.

For complete details on profiles.yml configuration and search order, refer to About profiles.yml.

Troubleshooting​

Common issues and resolutions:

  • dbt command not found: Ensure installation location is correctly added to your $PATH.
  • Version conflicts: Verify no existing dbt Core or dbt CLI versions are installed (or active) that could conflict with Fusion.
  • Installation permissions: Confirm your user has appropriate permissions to install software locally.

Frequently asked questions​

  • Can I revert to my previous dbt installation?

    Yes. If you want to test Fusion without affecting your existing workflows, consider isolating or managing your installation via separate environments or virtual machines.

More information about Fusion​

Fusion marks a significant update to dbt. While many of the workflows you've grown accustomed to remain unchanged, there are a lot of new ideas, and a lot of old ones going away. The following is a list of the full scope of our current release of the Fusion engine, including implementation, installation, deprecations, and limitations:

Was this page helpful?

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.

0
Loading