arch-secrets

arch-secrets fetches secrets from ARCH-Insight and gives them to a process when it starts. Use run to avoid storing credentials in a .env file.

Install

python -m pip install arch-secrets

Requires Python 3.9 or newer. The package has no third-party dependencies.

Configure access

Create an access token in ARCH-Insight under Secrets → Access tokens, then set it in the environment where the command will run:

export ARCH_SECRETS_TOKEN='your-access-token'

The token is scoped to the project and environment selected when it is created. The CLI does not accept a project or environment override, so it cannot use the token to request a different scope. The API defaults to https://arch-insight.com; set ARCH_API_URL when using another ARCH-Insight deployment.

Run a command with secrets

arch-secrets run -- npm start
arch-secrets run -- python app.py

The CLI fetches the token's secrets and adds them to the child process environment. It does not write a secrets file or print secret values. Existing environment variables are inherited, and fetched values take precedence when names overlap. Add --verbose before run to print the project, environment, path, and number of values fetched (never the values themselves).

Use --path to fetch a folder within the token's scope:

arch-secrets --path /database run -- python migrate.py

Export dotenv

Some tools only read dotenv files. export writes dotenv-formatted values to standard output, so choose explicitly where that output goes:

arch-secrets export > .env

Treat the resulting file as a secret: keep it out of version control and remove it when it is no longer needed.

Push dotenv values

push sends values from a dotenv file (or standard input) into the token's scope. It reports key names and counts, never values. Existing keys not present in the input are preserved unless --prune is explicitly supplied.

arch-secrets push .env
arch-secrets push --dry-run .env

The token must have write access for push. Use --path /folder before push to write within a folder in its scope.

Commands

arch-secrets [--api URL] [--token TOKEN] [--path PATH] [-v] run -- COMMAND...
arch-secrets [--api URL] [--token TOKEN] [--path PATH] export
arch-secrets [--api URL] [--token TOKEN] [--path PATH] push [FILE] [--prune] [--dry-run]

Prefer ARCH_SECRETS_TOKEN over --token: command-line arguments can be visible in process listings and shell history.