use-maskrun

Use maskrun instead of executing shell commands directly when commands may print environment variables, API keys, tokens, passwords, secrets, credentials, CI...

Core Rule

Run potentially sensitive commands through maskrun -- instead of executing them directly.

Use this form:

maskrun -- <command> [args...]

Examples:

maskrun -- cargo test
maskrun -- npm run build
maskrun -- curl "https://api.example.com?key=${API_KEY}"
maskrun -- sh -c 'echo "$API_KEY"'
maskrun -- echo "$API_KEY"
maskrun -- cat openclaw.json

When To Wrap

Wrap commands when any of these are true:

• The command may print environment variables or configuration values.
• The command touches .env, credentials, tokens, API keys, cloud config, CI config, auth headers, or debug dumps.
• The command runs tests, build scripts, package scripts, setup scripts, or third-party CLIs that may echo environment state.
• The command sends API requests using credentials from the environment.
• The command is being run by an agent and the output may be saved in logs or transcripts.

When Direct Execution Is Fine

Direct execution is usually fine for commands that only inspect local source files or repository metadata and do not run project code, read env files, or print environment values.

Examples:

rg "maskrun" src tests README.md
sed -n '1,120p' Cargo.toml
git diff -- src/main.rs

If unsure, use maskrun --.

Command Handling

Keep the wrapped command unchanged after --.

Do:

maskrun -- bash -lc 'echo "$API_KEY"'
maskrun -- env
maskrun -- cargo test -- --nocapture

Do not rewrite the child command arguments to make masking work. maskrun filters stdout and stderr while preserving the child command's normal inherited environment and exit code.

Installation

If maskrun is not installed, check the latest installation instructions before running sensitive commands.

Start from the GitHub repository or latest release page:

• https://github.com/ctxinf/agent-env-guard
• https://github.com/ctxinf/agent-env-guard/releases/latest

Use the install method documented there for the current platform. Common options include:

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/ctxinf/agent-env-guard/releases/latest/download/agent-env-guard-installer.sh | sh
brew install ctxinf/tap/agent-env-guard
npm install @ctxinf/agent-env-guard@latest

On Windows, use the PowerShell command from the latest release page.

After installation, verify:

maskrun --help

Configuration

maskrun uses a TOML config to decide which environment variable values should be masked.

Rules match environment variable names, not output text patterns. When a variable name matches exact, glob, or regex, its value is masked by exact string replacement in stdout and stderr.

Default config locations:

• Linux / Unix: $XDG_CONFIG_HOME/maskrun/config.toml or $HOME/.config/maskrun/config.toml
• macOS: $HOME/Library/Application Support/maskrun/config.toml
• Windows: %APPDATA%\maskrun\config.toml

Example config:

[filter]
exact = [
  "API_KEY",
  "SECRET",
  "PASSWORD",
]

glob = [
  "*_KEY",
  "*_TOKEN",
  "*_SECRET",
  "*_PASSWORD",
]

regex = [
  "(?i)^.*password.*$",
]

If the user needs to change masking rules, edit the default config file above or pass a project-specific config:

maskrun --config ./maskrun.toml -- <command> [args...]

Use --verbose to inspect which environment variable names matched without printing their raw values:

maskrun --verbose -- <command> [args...]

Safety Boundary

Treat maskrun as output masking only.

It does not sandbox the child process, block network access, prevent file writes, manage credentials, or stop the child command from reading environment variables. It reduces accidental exposure in terminal output, logs, and agent transcripts.