Skip to main content

​
idw exec

idw exec runs a subprocess with vault credentials automatically injected as environment variables. Credentials never appear in shell history, and child processes cannot access the vault passphrase or session tokens. 
idw exec [options] -- <command...>

​
Options

OptionDescription
-p, --passport <refs...>Passport ID(s) or name(s) to inject (repeatable)
--as <mapping...>Override env var names: PASSPORT_REF=ENV_VAR (repeatable)
--allInject all active passports from the vault
--platform <platform>Filter passports by platform (used with --all)
--tag <tags...>Filter passports by tag(s) (used with --all)
-P, --path <path>Path to vault file
--dry-runPrint what would be injected without executing
--no-inheritDo not inherit parent process environment variables
--cwd <dir>Working directory for the child process
--actor <name>Actor name for audit logging (default: $USER or cli-exec)

​
Usage examples

# Run a Python script with an OpenAI key injected
idw exec -p "OpenAI Production" -- python agent.py

# Inject multiple credentials
idw exec -p openai-key -p anthropic-key -- node multi-model.js

# Override the environment variable name
idw exec -p my-key --as my-key=CUSTOM_API_KEY -- ./run.sh

# Inject all active passports for a platform
idw exec --all --platform openai -- python train.py

# Dry run to preview injected variables
idw exec -p prod-key --dry-run -- echo test

# Use with npm/yarn scripts
idw exec -p openai-key -- npm run start

​
How it works

1

Resolve passports

Passports are resolved by ID, name (case-insensitive), or filter (--all, --platform, --tag).
2

Policy check

The policy engine evaluates each passport for the exec action. Denied passports block execution.
3

Map environment variables

Credentials are mapped using the platform-aware mapping table, explicit --as overrides, or the fallback IDW_{NAME} convention.
4

Collision detection

If two passports map to the same env var, exec fails with a clear error. Use --as to disambiguate.
5

Spawn child process

Credentials are injected into the child’s environment only. IDW_PASSPHRASE and IDW_SESSION_TOKEN are stripped from the child env.
6

Signal forwarding

SIGTERM, SIGINT, and SIGHUP are forwarded to the child process.
7

Audit logging

Every credential access is logged with command name, args, PID, env var names, exit code, and duration.
8

Exit code propagation

The child’s exit code is returned as idw exec’s exit code.

​
Platform environment variable mapping

idw exec automatically maps credentials to SDK-standard environment variable names:
PlatformCredential TypeEnvironment Variable
openaiapi-keyOPENAI_API_KEY
anthropicapi-keyANTHROPIC_API_KEY
awsapi-keyAWS_ACCESS_KEY_ID
awssecretAWS_SECRET_ACCESS_KEY
awssession-keysAWS_SESSION_TOKEN
githubapi-keyGITHUB_TOKEN
google-a2aapi-keyGOOGLE_API_KEY
azure-aiapi-keyAZURE_OPENAI_API_KEY
slackbot-tokenSLACK_BOT_TOKEN
langchainapi-keyLANGCHAIN_API_KEY
crewaiapi-keyOPENAI_API_KEY
mcpapi-keyMCP_API_KEY
openclawapi-keyOPENCLAW_API_KEY
For unknown platforms, the fallback is IDW_{PASSPORT_NAME} (uppercased, sanitized). Use --as for full control.
Use --dry-run to preview the environment variable mapping before running your command.

​
Security properties

  • Credentials exist only in the child process environment, never the parent shell
  • IDW_PASSPHRASE and IDW_SESSION_TOKEN are automatically stripped from the child env
  • No shell expansion — uses spawn with array arguments, not shell string interpolation
  • Credential values never appear in error messages
  • Policy engine is evaluated before any credential is injected
  • Complete audit trail with process-level metadata
idw exec uses direct process spawning (not a shell). If you need shell features like pipes or globbing in the child command, wrap it explicitly: idw exec -p key -- bash -c "echo \$OPENAI_API_KEY | wc -c".

​
Common patterns

​
CI pipeline credential injection

# GitHub Actions — inject credentials from a vault unlocked via session token
export IDW_SESSION_TOKEN="${{ secrets.IDW_TOKEN }}"
idw exec --all --platform openai -- npm test

​
Multi-model agent scripts

# Inject OpenAI and Anthropic keys for a multi-model agent
idw exec -p openai-prod -p anthropic-prod -- python multi_agent.py

​
Custom variable names

# Map a passport named "my-openai" to a custom env var
idw exec -p my-openai --as my-openai=MY_CUSTOM_KEY -- node app.js

​
Docker and containerized workflows

# Pass credentials into a Docker build or run
idw exec -p prod-key -- docker run -e OPENAI_API_KEY myimage:latest

​
Next steps

Authentication

Understand how vault passphrase resolution works including .env file support.

Policy engine

Configure rules that govern which credentials can be injected.

Audit log

Review the audit trail for every credential access through exec.