---
title: "Secure secrets handling"
description: "Protect secrets at the boundary between CircleCI and your systems. Understand command-line risks and apply mitigations such as protecting API tokens."
platform: "Cloud, Server"
doc_version: "Server"
last_updated: "2026-10-07"
---

> For current CircleCI product defaults, deprecated patterns, and Cloud/Server differences, see [AGENTS.md](https://circleci.com/docs/AGENTS.md).
>
> For the complete documentation index and site structure, see [llms.txt](https://circleci.com/docs/llms.txt).

# Secure secrets handling

Many builds must reference secret values entrusted to CircleCI. CircleCI understands that security is critical to every organization’s success. However, you can also take a few steps to help protect secrets at the boundary between CircleCI’s systems and yours.

## Risks of using secrets on the command-line

Unix and Linux shells can expose sensitive data in several ways. It is important to consider all of them when working with CircleCI on the command-line.

*   **Command history**: If you include a secret in a command’s parameters, such as `export MY_SECRET="value"` or `curl --header "authorization: Basic TOKEN"`, that value could be written into your shell’s history file, such as `.bash_history`. Anyone with access to that file could then retrieve the secret.
    
*   **Process arguments**: While a process is running, any user on the same system can view the command that started it. The easiest way to see this is by running `ps -ef`, but there are other methods as well. Critically, this information is exposed after environment variables have been interpreted, so that when running `mycommand "$MYVAR"`, `ps` will show `mycommand <value of MYVAR>`. On some older variants of Unix, such as AIX, it is also possible for all users to see all environment variables for any process.
    
*   **System logs**: Many systems log all commands executed using `sudo` for auditing. Many auditing services record all commands. Such services could potentially export those logs into systems that are not designed to keep secret data safe.
    
*   **Console output**: Depending on your threat model and what kind of console is in use, printing a secret to the console could carry risk. For example, use of screen-sharing tools for activities like pair-programming can lead to accidental, persistent exposure of secrets transited through untrusted videoconferencing providers, possibly even in video recordings. It is best to choose tools that print secrets to the console only when necessary and explicitly told to do so by the user.
    
*   **Persistent, unencrypted secrets on disk**: Although command-line tools commonly store secrets in home directory files, those files are accessible to all processes and persist over time, posing a risk.
    

## Mitigation techniques

This section covers several techniques to help mitigate the risks discussed above. We will focus on methods for using `curl` commands and [CircleCI CLI](https://circleci.com/docs/guides/server/toolkit/circleci-cli/) securely with the Bash shell.

### General precautions

Avoid running `env` or `printenv`, which will print the values of all environment variables, including secrets.

Avoid writing secrets into your shell history with the following techniques. However, note that turning off history will not prevent commands from being exposed through audit logs and `ps`:

*   Running `set +o history` before the sensitive commands will prevent them from being written to the history file. `set -o history` will turn history logging back on.
    
*   If your shell supports the `HISTCONTROL` environment variable, and it is set to `ignoreboth` or `ignorespace`, placing a space before your command will prevent it from being written to the history file.
    

Be aware that `export` is built in to Bash and other common shells. This means that, with precautions, you can avoid exposure of secrets to the history file, `ps`, and audit logs when using `export`:

*   Make sure to avoid writing to the shell history by using `set +o history` or `HISTCONTROL`.
    
*   Next, if unsure, verify that `export` is really a shell built-in by using the `type` command: `type export`.
    
*   Remember that information will still be exposed in your console, and make sure you are okay with that risk.
    
*   Follow the rest of the precautions on this page related to the use of environment variables.
    
*   As soon as you are finished using a secret with `export`, consider using `unset` to remove it from the shell. Otherwise, the `export` environment variable will still be available to all processes spawned from that console.
    

Another shell built-in, `read`, can be used to set an environment variable without exposing it to the console:

```shell
# Check that your version of read supports the -s option
help read

IFS='' read -r -s MY_VAR
# (enter your secret; press return when done)

# Alternatively, read from a file
IFS='' read -r MY_VAR < ~/.my_secret

# Or a process
secret_producer | IFS='' read -r MY_VAR

# Export the variable so that it is available to subprocesses
export MY_VAR
```

### Use the CircleCI CLI

Use the [CircleCI Local CLI](https://circleci.com/docs/guides/server/toolkit/circleci-cli/) instead of `curl` commands when possible. The CLI takes extra precautions to avoid leaking secrets when performing sensitive operations. For example, when [Creating Environment Variables](https://circleci.com/docs/guides/server/security/contexts/#creating-environment-variables), the CLI will prompt you to enter the secret rather than accepting it as a command line argument.

If writing a shell script that uses the CircleCI CLI, use the `<<<` construct in Bash to avoid exposing secrets. This construct does not spawn a new process while piping a value:

```bash
circleci context store-secret --org-id <org-id> <context-name> <secret-name> <<< "$MY_SECRET"
```

Using the `<<<` construct is more reliable than using `echo` or `printf`, which may or may not be shell built-ins and could potentially spawn a process.

### Protect the API token

When calling the CircleCI API with `curl` commands, you need to provide an API token. Several ways you can mitigate risk while supplying tokens are as follows:

*   Use a `.netrc` file: The [`.netrc` file format](https://everything.curl.dev/usingcurl/netrc.html), which is supported by several different tools, allows you to provide HTTP basic auth credentials in a file, rather than at the command-line.
    
    *   Create a file at a location of your choosing. The default used by some tools is `~/.netrc`. Be sure to `chmod 0600` this file before adding the secret, to prevent other users from viewing its contents.
        
    *   Add a line in the following format: `machine circleci.com login <your token> password`
        
    *   On CircleCI Server, use your Server hostname instead of `circleci.com` for `machine`.
        
    *   When invoking `curl` commands, tell it to look in your `.netrc` file for credentials: `curl --netrc-file ~/.netrc`
        
    
*   Write the `Circle-Token` header into a file. This requires cURL 7.55 or later, but is a more reliable solution than `.netrc`, because some tools that use `.netrc` files do not understand an empty password field:
    
    *   Create a file at a location of your choosing. Be sure to `chmod 0600` the file to prevent other users from viewing its contents.
        
    *   Add a line in the following format: `Circle-Token: <your token>`
        
    *   When invoking `curl` commands, tell it to read the header from a file: `curl --header @your_filename`
        
    
*   Pull the token directly from a tool designed to store secrets, such as 1Password. In this case, you can use [process substitution](https://en.wikipedia.org/wiki/Process_substitution) to retrieve the header without exposing it:
    
    *   `curl --header @<(command_to_retrieve_password)`
        
    *   If you are sure that `printf` is a built-in in your shell, it is also safe to write `curl --header @<(printf '%s\n' "$MYVAR")`, allowing you to use environment variables without exposing them through `ps`.
        
    

### Protect your secrets

Some API endpoints, such as [addEnvironmentVariableToContext](https://circleci.com/docs/api/v2/#operation/addEnvironmentVariableToContext), may require secrets to be sent in the body of `PUT` or `POST` requests. Several options to help conceal secrets sent in a request body are as follows:

*   Use a file to compose and store the request body. Be sure to `chmod 0600` this file before adding the secret value to prevent other users from viewing its contents.
    
    *   Point `curl` to this file by using the `@` directive: `curl --data @myfile`
        
    
*   Use a Heredoc to compose the request body, and pass it to cURL on stdin:
    
    ```shell
    curl --data @- <<EOF
    {"value":"some-secret-value"}
    EOF
    ```