Complete reference for all 32+ commands. Search below to find specific syntax, options, and usage examples.
The CLI is distributed as an npm package. You can install it globally using your preferred package manager.
xtra --version to ensure the CLI is correctly installed.npm install -g xtra-cliEssential commands for bootstrapping projects and injecting secrets.
Bootstraps a new project by creating an .xtrarc config file and linking it to the cloud.
xtra init [options]On execution, you'll see the following prompts:
What is your project named? my-projectWould you like to link an existing XtraSecurity project?> Yes, link existing project No, create a new projectAfter the prompts, xtra init will create an .xtrarc file in your directory and authenticate your environment.
| -y, --yes | Skip interactive prompts |
| --project <id> | Specify existing project ID |
xtra init --project prj_abc123 -yAuthenticates your CLI session. Opens browser for SSO by default.
xtra login [options]On execution, you'll see the following prompts:
> Opening browser to https://xtrasecurity.com/auth/device> Successfully authenticated as user@example.comThis command securely stores a session token in your local OS keychain.
| --sso | Force SSO flow |
| --key <token> | Machine identity authentication for CI/CD |
xtra login --key xs_prod_123456789Terminates session and securely purges all local encrypted caches.
xtra logoutOn execution, you'll see the following prompts:
> Successfully logged out.> Local caches securely purged.This removes your session token and clears any local fallback secrets to ensure complete security.
xtra logoutFetches secrets and injects them securely into a child process memory.
xtra run [options] <command> [args...]This is the most common command. It securely fetches your environment variables and runs the specified child process (e.g. your dev server) without writing secrets to the disk.
| --env <name> | Target environment (e.g., production) |
| --project <id> | Override .xtrarc project context |
xtra run --env production -- npm run startManage secrets. Subcommands: ls, get, set, rm.
xtra secrets <command> [options]| --env <name> | Target environment |
| --json | JSON output for 'ls' |
| -y, --yes | Skip confirmation for 'rm' |
xtra secrets set API_KEY [VALUE]Manage project contexts, environments, and secret branching.
Manage and list project contexts.
xtra project <command> [options]Lists all projects you have access to, or modifies the active project link.
xtra project ls --jsonList and manage environments within the active project.
xtra env <command> [options]Lists or modifies environments like staging, dev, prod.
xtra env lsCreate and list isolated secret branches for feature development.
xtra branch <command> [options]Secret branching works just like git branching. It isolates your secret changes before merging them to the main environment.
xtra branch create feat/new-payment-gatewaySwitch the active branch context. All subsequent 'xtra run' commands will pull from this branch.
xtra checkout [options] [branchName]On execution, you'll see the following prompts:
> Switched to branch 'feat/new-payment-gateway'> 14 secrets loaded in local context.Sets the active branch context for your current terminal session.
xtra checkout feat/new-payment-gatewayManage named configuration profiles for multiple XtraSecurity instances.
xtra profile <command> [options]Useful when switching between personal and work accounts without logging out.
xtra profile use personalToggle cloud/local mode for offline development. Uses fallback .env if cloud is unreachable.
xtra local <command>Enables a fallback for offline development. If the cloud is unreachable, it will use a locally cached, encrypted fallback.
xtra local enablePowerful developer experience features for live-reloading and dry-runs.
Live reload. Automatically restarts your child process whenever secrets change in the cloud.
xtra watch [options] <command> [args...]Great for hot-reloading frontend apps when a teammate updates a shared secret.
xtra watch -- npm run devDry-run mode. Shows exactly what variables would be injected without executing the actual command.
xtra simulate [options] [command]On execution, you'll see the following prompts:
> STRIPE_KEY=sk_test_***> DB_URL=postgres://***> 2 variables would be injected. Process execution skipped.Verify your injection pipeline without side effects.
xtra simulate -- npm run buildLaunches an interactive, terminal-based (TUI) secrets dashboard.
xtra uiProvides a rich, interactive terminal UI if you prefer not to use the web interface.
xtra uiStrict headless mode tailored for CI/CD pipelines. Disables all interactive prompts.
xtra ci <command> [options]Bypasses all prompts, failing immediately on errors. Perfect for GitHub Actions or GitLab CI.
xtra ci run -- npm testGenerate auto-completion scripts for your shell (bash, zsh, powershell).
xtra completion [options] [shell]Install autocomplete for your specific shell to speed up your workflow.
xtra completion zsh > ~/.xtra-completionAuditing, zero-downtime rotation, and Just-In-Time access controls.
Submit a Just-In-Time (JIT) access request for a sensitive environment.
xtra access <command> [options]On execution, you'll see the following prompts:
Requesting JIT access for Production...> Request sent to admins.> Approved by admin@company.com> Access granted for 1h.This workflow integrates directly with your team's Slack or email approvals.
xtra access request --env prod --reason "Debug" --duration 1hView cryptographically verified audit logs for secret access and modifications.
xtra logs [options]Fetches tamper-proof audit trails from the server for compliance reporting.
xtra logs --days 7Scan your local codebase for hardcoded secrets or misconfigured .env files.
xtra scan [options]On execution, you'll see the following prompts:
> Scanning .> Found 1 exposed AWS key in .env.local> Action Required: Rotate immediatelyDetects over 100+ patterns of exposed secrets before you commit them.
xtra scan . --strictView the version history of a specific secret.
xtra history [options] <key>View past versions, who changed them, and when they were changed.
xtra history DATABASE_URLInstantly revert a secret to a previous version.
xtra rollback [options] <key>Immediately restore a prior version if a bad secret deployment breaks production.
xtra rollback STRIPE_KEY --version 3Zero-Downtime Shadow Mode rotation. Updates a secret and slowly drains traffic from the old one.
xtra rotate [options] <key>Perform zero-downtime rotation. Extremely useful for high-availability database credential rotation.
xtra rotate AWS_ACCESS_KEYExporting, templating, and diagnosing connectivity issues.
Bulk migrate secrets in various formats (JSON, Dotenv, CSV).
xtra export [options]Backup your secrets or migrate them locally.
xtra export --format dotenv > .env.backupBulk import secrets from a file.
xtra import [options] <file>Upload multiple secrets at once from existing dotenv files.
xtra import --format dotenv .env.backupSecret templating engine. Injects secrets into static configuration files (e.g., docker-compose.yml).
xtra template [options]Inject secrets into a static template file before deployment.
xtra template ./config.tpl.yaml > ./config.yamlCompare secrets between two environments or between local cache and remote.
xtra diff [options] [env1] [env2]See exactly what changed between staging and production environments.
xtra diff staging productionDiagnose common setup issues, network connectivity, and token validity.
xtra doctor [options]On execution, you'll see the following prompts:
> Checking connection... OK> Verifying token... OK> Checking workspace context... OK All systems operational.Run this command first if you're experiencing any authentication or network issues.
xtra doctor