CLI Reference
npx @keywaysh/cli init
Or install globally:
- npm
- pnpm
- Yarn
npm install -g @keywaysh/cli
pnpm add -g @keywaysh/cli
yarn global add @keywaysh/cli
brew install keywaysh/tap/keyway
Commands
keyway init
Initialize a vault for the current repository. Requires admin access.
keyway init
If not logged in, opens browser for GitHub OAuth.
keyway push
Push local secrets to Keyway.
keyway push [options]
| Option | Default | Description |
|---|---|---|
-e, --env <name> | development | Target environment |
-f, --file <path> | .env | Source file |
-y, --yes | false | Skip confirmation |
keyway push # Push .env to development
keyway push -e production # Push to production
keyway push -f .env.prod -e production # Custom file
Push replaces all secrets in the environment. If a secret exists in Keyway but not in your local file, it will be deleted.
keyway pull
Pull secrets from Keyway to local file.
keyway pull [options]
| Option | Default | Description |
|---|---|---|
-e, --env <name> | development | Source environment |
-f, --file <path> | .env | Output file |
-y, --yes | false | Skip confirmation |
keyway pull # Pull development to .env
keyway pull -e staging # Pull staging
keyway pull -e staging -f .env.stg # Compare environments
keyway run
Run a command with secrets injected into the environment. Secrets are fetched from the vault and kept in memory (RAM) only, never written to disk.
keyway run [options] -- <command>
| Option | Default | Description |
|---|---|---|
-e, --env <name> | development | Environment to use |
# Run with default environment (development)
keyway run -- npm run dev
# Run with specific environment
keyway run -e production -- ./deploy.sh
# Run any command
keyway run -- python3 script.py
AI Agents Integration
When using AI coding assistants like Claude Code, Gemini CLI, or GitHub Copilot CLI, you want to avoid giving them access to your .env files (which they can read if they are on disk).
keyway run solves this:
- The AI agent runs
keyway run -- npm test. - Secrets are injected in memory.
- Tests pass.
- The AI never sees the actual secret values, only the success/failure output.
This is the most secure way to use secrets locally or in CI/CD, as no .env file is created.
keyway set
Set a single secret in the vault.
keyway set <KEY> [VALUE] [options]
| Option | Default | Description |
|---|---|---|
-e, --env <name> | development | Target environment |
-y, --yes | false | Skip confirmation |
keyway set API_KEY # Prompt for value (masked)
keyway set API_KEY=sk_live_xxx # Set with inline value
keyway set API_KEY -e production # Set in specific environment
Use keyway set for quick, single-secret updates without touching your .env file. Perfect for rotating a single key.
keyway diff
Compare secrets between two environments.
keyway diff [env1] [env2] [options]
| Option | Default | Description |
|---|---|---|
--show-values | false | Show actual value differences (sensitive!) |
--keys-only | false | Only show key names |
--json | false | Output as JSON |
keyway diff # Interactive selection
keyway diff production staging # Compare two environments
keyway diff dev prod --show-values # Show value differences
keyway scan
Scan files for potential secret leaks (API keys, tokens, passwords).
keyway scan [path] [options]
| Option | Default | Description |
|---|---|---|
-e, --exclude <pattern> | - | Additional directories to exclude |
--json | false | Output as JSON (for CI) |
--show-all | false | Show all matches including potential false positives |
keyway scan # Scan current directory
keyway scan ./src # Scan specific directory
keyway scan --json # For CI/CD integration
keyway scan -e test -e fixtures # Exclude directories
Consider adding keyway scan to your pre-commit hooks to catch leaks before they reach git history.
keyway doctor
Run diagnostic checks.
keyway doctor [options]
| Option | Description |
|---|---|
--json | Output as JSON |
--strict | Treat warnings as failures |
Checks: authentication, token validity, git repo, GitHub remote, vault existence, permissions, network.
keyway login
Authenticate with GitHub.
keyway login # OAuth (opens browser)
keyway login --token # Use fine-grained PAT
Token stored securely in the system keyring (macOS Keychain, Linux Secret Service, Windows Credential Manager).
keyway logout
Clear stored authentication.
keyway logout
keyway connect
Connect to an external provider.
keyway connect <provider>
Supported providers: vercel, railway, netlify
keyway connect vercel # Opens browser for Vercel OAuth
keyway connect railway # Prompts for Railway API token
keyway connections
List connected providers.
keyway connections
keyway disconnect
Disconnect from a provider.
keyway disconnect <provider>
keyway sync
Sync secrets with a provider.
keyway sync <provider> [options]
| Option | Default | Description |
|---|---|---|
-e, --environment <env> | production | Keyway environment |
--provider-env <env> | production | Provider environment |
--project <name> | - | Provider project |
--pull | false | Import from provider |
--allow-delete | false | Delete missing secrets |
-y, --yes | false | Skip confirmation |
keyway sync vercel # Push to Vercel
keyway sync vercel -e staging --provider-env preview
keyway sync vercel --pull # Import from Vercel
keyway sync vercel --allow-delete -y # Full sync
Global Options
| Option | Description |
|---|---|
--help, -h | Show help |
--version, -V | Show version |
--no-login-prompt | Fail if not authenticated (for CI/CD) |
Environment Variables
| Variable | Description |
|---|---|
KEYWAY_TOKEN | Override stored token |
KEYWAY_API_URL | API URL (default: https://api.keyway.sh) |
KEYWAY_DISABLE_TELEMETRY | Set 1 to disable analytics |
KEYWAY_TOKEN=ghp_xxx keyway pull
Exit Codes
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | General error |
| 2 | Authentication required |
| 3 | Vault not found |
| 4 | Permission denied |
| 5 | Network error |
Scripting
#!/bin/bash
set -e
keyway pull --yes
npm start
Troubleshooting
"No vault found" → Run keyway init
"Authentication required" → Run keyway login
"Permission denied" → Need GitHub repo access
Debug mode:
keyway pull --verbose