---
title: "Use environment variables"
description: "Define an environment variable, refer to it from a project file, and make sure CAT sees it — on Windows and Linux, on a laptop and in a pipeline"
url: "https://docs.justcat.it/how-to-guides/organize-and-run-tests/use-environment-variables/"
---
# Use environment variables


This guide is the plumbing: defining a variable, referring to it, checking it is visible. What CAT does with the value once it has it — where expansion applies, the rules — is the [Environment variables](https://docs.justcat.it/reference/project-file/environment-variables/ "Environment variables") reference.

## Define the variable

Where you define it decides how long it lives and who sees it:

| Level | Seen by | Use for |
|---|---|---|
| Session | the one shell session; gone when it closes | trying things out — not for secrets, the command line lands in the shell history |
| User | every new session of that user | a developer's machine |
| Machine | every new session of every user | a shared test server, a self-hosted agent |
| Pipeline | the step the pipeline maps it into | CI/CD — the platform's variable or secret store; see [Integrations](https://docs.justcat.it/reference/integrations/ "Integrations") |


**Windows**


Session, in PowerShell:

```powershell
$Env:DWH_CONNECTION_STRING = 'Server=dwh;Database=DWH;Integrated Security=true'
```

User or machine, for good: *Settings → System → Advanced system settings → Environment Variables*, or from PowerShell:

```powershell
[Environment]::SetEnvironmentVariable('DWH_CONNECTION_STRING', 'Server=dwh;…', 'User')     # or 'Machine'
```

A user- or machine-level variable is seen only by sessions started after it was set — open a new terminal; CAT Studio: start it again.


**Linux and macOS**


Session:

```bash
export DWH_CONNECTION_STRING='Server=dwh;Database=DWH;User Id=cat;Password=…'
```

For good, put the `export` line into the shell's profile (`~/.bashrc`, `~/.zshrc`) or, for every user and for services, into `/etc/environment`. Variable names are **case-sensitive** here — `DWH_CONNECTION_STRING` and `dwh_connection_string` are two variables; on Windows they are one.


**Pipeline**


Define the value in the platform's store — Azure DevOps variable group, GitLab CI/CD variables, GitHub secrets, Jenkins credentials — and map it into the environment of the step that runs CAT; a secret is never mapped automatically:

```yaml
# Azure DevOps
- task: PowerShell@2
  inputs: { pwsh: true, script: 'Invoke-CatProject' }
  env:
    DWH_CONNECTION_STRING: $(DWH_CONNECTION_STRING)
```

The platform guides show it for [Azure DevOps](https://docs.justcat.it/how-to-guides/pipelines-and-schedulers/cat-in-azure-devops-pipelines/ "CAT in Azure DevOps Pipelines"), [GitLab](https://docs.justcat.it/how-to-guides/pipelines-and-schedulers/cat-in-gitlab/ "CAT in GitLab"), [GitHub Actions](https://docs.justcat.it/how-to-guides/pipelines-and-schedulers/cat-in-github-actions/ "CAT in GitHub Actions") and [Jenkins](https://docs.justcat.it/how-to-guides/pipelines-and-schedulers/cat-in-jenkins/ "CAT in Jenkins").




## Refer to it from the project file

Write the name between percent signs, exactly as defined:

```yaml
Data sources:
- Name: DWH
  Provider: SqlServer@2
  Connection string: "%DWH_CONNECTION_STRING%"

Tests:
- Name: Departures for terminal %TERMINAL_NUMBER% are loaded
  Data source: DWH
  Query: SELECT * FROM FACT.DEPARTURES WHERE Terminal = %TERMINAL_NUMBER%
  Expectation: set is not empty
```

> **🐱:** **Quote a value that starts with `%`.** A percent sign at the start of a YAML value has a meaning of its own; without the quotes CAT reports an unexpected token on that line. Inside a longer value, as in the query above, no quotes are needed.



A whole connection string can come from a variable, or only its secret parts — the user and the password — and one variable can be used in as many places as needed. Expansion happens wherever a definition lives: the project file, other YAML files, a database table, a worksheet.

## Check that CAT can see it

CAT sees exactly the variables the process it runs in sees. When a value reaches a provider with the percent signs still in it — an invalid connection string, a syntax error in a query — the variable was not replaced. Print it in the session you run CAT from:


**Windows**


```powershell
$Env:DWH_CONNECTION_STRING
```


**Linux and macOS**


```bash
echo "$DWH_CONNECTION_STRING"
```




Nothing printed means the session does not know the variable, and neither does CAT. The usual causes: the variable was created a moment ago and this session is older than it; the name is misspelled (or, on Linux and macOS, cased differently); in a pipeline the variable is not mapped into the step. Until the session prints a value, CAT will not see one either.

## Related

* [Environment variables](https://docs.justcat.it/reference/project-file/environment-variables/ "Environment variables") — what CAT replaces, where, and the rules.
* [Work with secrets](https://docs.justcat.it/how-to-guides/organize-and-run-tests/work-with-secrets/ "Work with secrets") — keeping passwords and tokens out of the project file.