CLI tool

Overview

The PassAgent CLI provides terminal access to your vault for scripting, CI/CD pipelines, and power-user workflows. It supports authentication, credential retrieval, password generation, and secret injection into subprocess environments. The CLI communicates with your PassAgent server over HTTPS and stores session data locally in ~/.passagent/session.json with restricted file permissions (0600).

Installation

npm
From source

npm install -g @passagent/cli

git clone https://github.com/passagent/passagent.git
cd passagent/packages/cli
npm install && npm run build
npm link

Verify the installation:

passagent --version
# 0.1.0

Authentication

Before using any vault commands, you must authenticate. The CLI supports both interactive and non-interactive login.

passagent login

You will be prompted for your email and master password. The CLI authenticates against /api/auth/cli-login and stores the returned session token.

🔐 PassAgent CLI Login

Email: user@example.com
Master Password: ********
✓ Authenticated
✓ Logged in as user@example.com
  Session saved to /Users/you/.passagent/session.json

For CI/CD environments where interactive prompts are not available, use the --api-key flag:

passagent login --email user@example.com --api-key pa_sk_live_abc123

Set the PASSAGENT_API_URL environment variable to point the CLI at a self-hosted PassAgent instance. The default is https://passagent.com.

Session management

Command	Description
`passagent login`	Authenticate and save session
`passagent logout`	Clear session and lock vault
`passagent status`	Show current session info

The status command displays the current lock state, authenticated email, server URL, and session age:

🔓 Vault is unlocked
  Email:    user@example.com
  Server:   https://passagent.com
  Session:  12 minutes old

Session data is stored at ~/.passagent/session.json with 0600 permissions (owner read/write only). The configuration directory is created with 0700 permissions.

Vault commands

Get a credential

Retrieve a credential by name or ID:

# Display full credential (password masked)
passagent get "GitHub"

# Get a specific field
passagent get "GitHub" --field password

# Copy password to clipboard
passagent get "GitHub" --copy

# Output as JSON
passagent get "GitHub" --json

When displaying a full credential, the password is masked by default. Use --field password to retrieve the plaintext value, or --copy to send it directly to the clipboard without printing it.

Flag	Short	Description
`--field <field>`	`-f`	Return a specific field (password, username, url)
`--copy`	`-c`	Copy to clipboard instead of printing
`--json`		Output as JSON

List vault items

# List all items
passagent list

# Filter by type
passagent list --type password
passagent list --type note

# Output as JSON
passagent list --json

The list command displays each item with its name, username, and URL in a compact format:

  Vault (42 items)

  ● GitHub
    user: octocat
    url:  https://github.com
  ● AWS Production
    user: admin@company.com
    url:  https://aws.amazon.com
  ...

Search

Search across names, usernames, and URLs:

passagent search "aws"
passagent search "production" --json

Password generator

Generate cryptographically secure passwords directly from the terminal:

# Default: 24-character password with letters, numbers, symbols
passagent generate

# Custom length
passagent generate --length 32

# Exclude symbols
passagent generate --no-symbols

# Exclude numbers
passagent generate --no-numbers

# Copy to clipboard
passagent generate --copy

Flag	Short	Default	Description
`--length <n>`	`-l`	24	Password length (min: 8, max: 128)
`--no-symbols`		false	Exclude special characters
`--no-numbers`		false	Exclude digits
`--copy`	`-c`	false	Copy to clipboard

The generator uses crypto.randomBytes() for cryptographically secure random selection from the character set. The character pool includes:

Lowercase: a-z (26 characters)
Uppercase: A-Z (26 characters)
Numbers: 0-9 (10 characters, unless --no-numbers)
Symbols: !@#$%^&*()_+-=[]{}|;:,.<>? (27 characters, unless --no-symbols)

Without --copy, the generated password is printed to stdout. Be aware that terminal scrollback and shell history may retain the value. Use --copy when possible to avoid leaving passwords in terminal output.

Secret references

PassAgent defines a URI scheme for referencing vault secrets: pa://item-name/field. This allows secrets to be referenced declaratively in configuration files and scripts without embedding plaintext values.

URI format

pa://[item-name]/[field]

Component	Description	Examples
`item-name`	Credential name (case-insensitive match)	`GitHub`, `AWS Production`, `Database`
`field`	Field to extract	`password`, `username`, `url`, `key`

Resolve a reference

# Print the resolved value to stdout
passagent ref pa://GitHub/password

# Use in a pipeline
export DB_PASS=$(passagent ref pa://Database/password)

The ref command writes the raw value to stdout with no trailing newline, making it safe for use in command substitution and piping.

Inject secrets into a command

The inject command resolves secret references and passes them as environment variables to a subprocess:

passagent inject \
  -e DB_HOST=pa://Database/url \
  -e DB_USER=pa://Database/username \
  -e DB_PASS=pa://Database/password \
  -- node server.js

The subprocess inherits the current environment plus the resolved secret variables. The CLI displays resolution status on stderr so it does not interfere with the subprocess stdout:

  ✓ DB_HOST ← pa://Database/url
  ✓ DB_USER ← pa://Database/username
  ✓ DB_PASS ← pa://Database/password

  Running: node server.js

Literal values (not starting with pa://) can be mixed with secret references in the same inject command. For example: -e NODE_ENV=production -e DB_PASS=pa://Database/password.

CI/CD integration example

# GitHub Actions
steps:
  - name: Deploy
    env:
      PASSAGENT_API_URL: ${{ secrets.PASSAGENT_URL }}
    run: |
      passagent login --api-key ${{ secrets.PASSAGENT_API_KEY }}
      passagent inject \
        -e AWS_ACCESS_KEY_ID=pa://AWS/key \
        -e AWS_SECRET_ACCESS_KEY=pa://AWS/secret \
        -- aws s3 sync ./dist s3://my-bucket
      passagent logout

Command reference

Command	Arguments	Description
`passagent login`	`[--email] [--api-key]`	Authenticate and unlock vault
`passagent logout`		Lock vault and clear session
`passagent status`		Show vault lock status and session info
`passagent get`	`<name> [-f field] [-c] [--json]`	Get a credential by name or ID
`passagent list`	`[-t type] [--json]`	List all vault items
`passagent search`	`<query> [--json]`	Search vault items
`passagent generate`	`[-l length] [--no-symbols] [--no-numbers] [-c]`	Generate a secure password
`passagent ref`	`<uri>`	Resolve a secret reference URI
`passagent inject`	`-e <mappings...> -- <command>`	Run command with injected secrets

Environment variables

Variable	Default	Description
`PASSAGENT_API_URL`	`https://passagent.com`	API server URL

Security considerations

Session file permissions: the session file is created with 0600 and the config directory with 0700. Only the owning user can read or write session data.
No master password storage: the CLI does not store your master password. It stores only the session token returned by the server after successful authentication.
Clipboard clearing: when using --copy, be aware that clipboard contents persist until overwritten. Consider using a clipboard manager that supports automatic clearing.
Secret injection isolation: injected secrets exist only in the subprocess environment. They are not written to disk and do not appear in the parent process environment.
Logout on completion: in CI/CD pipelines, always call passagent logout after operations are complete to clear the session file from the build environment.

Setup

Operations

Overview

Installation

Authentication

Session management

Vault commands

Get a credential

List vault items

Search

Password generator

Secret references

URI format

Resolve a reference

Inject secrets into a command

CI/CD integration example

Command reference

Environment variables

Security considerations

Setup

Operations

​Overview

​Installation

​Authentication

​Interactive login

​Non-interactive login

​Session management

​Vault commands

​Get a credential

​List vault items

​Search

​Password generator

​Secret references

​URI format

​Resolve a reference

​Inject secrets into a command

​CI/CD integration example

​Command reference

​Environment variables

​Security considerations

Overview

Installation

Authentication

Interactive login

Non-interactive login

Session management

Vault commands

Get a credential

List vault items

Search

Password generator

Secret references

URI format

Resolve a reference

Inject secrets into a command

CI/CD integration example

Command reference

Environment variables

Security considerations