SecretHub CLI

Command-line interface for SecretHub secrets management platform.

Installation

From Release Binary

# Download the latest release
curl -LO https://github.com/secrethub/secrethub/releases/latest/download/secrethub

# Make it executable
chmod +x secrethub

# Move to PATH
sudo mv secrethub /usr/local/bin/

From Source

# Clone the repository
git clone https://github.com/secrethub/secrethub.git
cd secrethub

# Build the CLI
mix deps.get
mix escript.build

# Install to PATH
sudo cp secrethub /usr/local/bin/

Quick Start

Authentication

# Login with AppRole credentials
secrethub login --role-id <your-role-id> --secret-id <your-secret-id>

# Check authentication status
secrethub whoami

Managing Secrets

# List all secrets
secrethub secret list

# Get a secret value
secrethub secret get prod.db.password

# Create a new secret
secrethub secret create dev.api.key --value "sk-1234567890"

# Update an existing secret
secrethub secret update prod.db.password --value "new-password"

# Delete a secret
secrethub secret delete dev.api.key

# View secret version history
secrethub secret versions prod.db.password

# Rollback to a previous version
secrethub secret rollback prod.db.password 2

Managing Policies

# List all policies
secrethub policy list

# Get policy details
secrethub policy get developers

# Create a policy from template
secrethub policy create --from-template read_only --name "Developers"

# Delete a policy
secrethub policy delete old-policy

# List available policy templates
secrethub policy templates

Managing Agents

# List connected agents
secrethub agent list

# Get agent status
secrethub agent status agent-123

# Stream agent logs
secrethub agent logs agent-123

Configuration

# List all configuration
secrethub config list

# Get a configuration value
secrethub config get server_url

# Set a configuration value
secrethub config set server_url https://secrethub.example.com

Shell Completion

SecretHub CLI provides powerful shell completion for both Bash and Zsh, including:

Bash Completion

Installation

Option 1: System-wide (requires sudo)

sudo secrethub completion bash > /etc/bash_completion.d/secrethub
source ~/.bashrc

Option 2: User-local

mkdir -p ~/.bash_completion.d
secrethub completion bash > ~/.bash_completion.d/secrethub

# Add to ~/.bashrc:
echo 'if [ -f ~/.bash_completion.d/secrethub ]; then
    . ~/.bash_completion.d/secrethub
fi' >> ~/.bashrc

source ~/.bashrc

Option 3: macOS with Homebrew

# Install bash-completion if not already installed
brew install bash-completion

# Install secrethub completion
secrethub completion bash > $(brew --prefix)/etc/bash_completion.d/secrethub
source ~/.bash_profile

Testing

After installation, test by typing:

secrethub sec<TAB>
# Should complete to: secrethub secret

secrethub secret <TAB>
# Should show: list get create update delete versions rollback

secrethub --format <TAB>
# Should show: json table yaml

Troubleshooting

If completion doesn't work:

  1. Ensure bash-completion is installed:

    • Debian/Ubuntu: sudo apt install bash-completion
    • RHEL/CentOS: sudo yum install bash-completion
    • macOS: brew install bash-completion

  2. Restart your shell or source your rc file

  3. Check that secrethub is in your PATH:

    which secrethub

Zsh Completion

Installation

Option 1: User-local (recommended)

# Create completion directory
mkdir -p ~/.zsh/completion

# Generate completion file
secrethub completion zsh > ~/.zsh/completion/_secrethub

# Add to ~/.zshrc (BEFORE compinit):
echo 'fpath=(~/.zsh/completion $fpath)
autoload -Uz compinit
compinit' >> ~/.zshrc

# Reload configuration
source ~/.zshrc

Option 2: System-wide (requires sudo)

sudo secrethub completion zsh > /usr/local/share/zsh/site-functions/_secrethub

# Restart your shell
exec zsh

Option 3: oh-my-zsh

# Create plugin directory
mkdir -p ~/.oh-my-zsh/custom/plugins/secrethub

# Generate completion file
secrethub completion zsh > ~/.oh-my-zsh/custom/plugins/secrethub/_secrethub

# Add to plugins in ~/.zshrc:
# plugins=(... secrethub)

source ~/.zshrc

Testing

After installation, test by typing:

secrethub sec<TAB>
# Should show: secret -- Manage secrets

secrethub secret <TAB>
# Should show all subcommands with descriptions

secrethub --format <TAB>
# Should show: json table yaml

Troubleshooting

If completion doesn't work:

  1. Check that fpath includes your completion directory:

    echo $fpath

  2. Clear completion cache:

    rm -f ~/.zcompdump*
compinit

  3. Ensure compinit is called AFTER adding to fpath in your ~/.zshrc

  4. Check that secrethub is in your PATH:

    which secrethub

Global Options

All commands support these global options:

Output Formats

Table (default)

Human-readable table format:

secrethub secret list
PATH                          VERSION  UPDATED
prod.db.password              3        2024-01-15 10:30:45
dev.api.key                   1        2024-01-14 09:15:20

JSON

Machine-readable JSON format:

secrethub secret list --format json
[
  {
    "path": "prod.db.password",
    "version": 3,
    "updated_at": "2024-01-15T10:30:45Z"
  },
  {
    "path": "dev.api.key",
    "version": 1,
    "updated_at": "2024-01-14T09:15:20Z"
  }
]

YAML

YAML format for configuration files:

secrethub secret list --format yaml
- path: prod.db.password
  version: 3
  updated_at: '2024-01-15T10:30:45Z'
- path: dev.api.key
  version: 1
  updated_at: '2024-01-14T09:15:20Z'

Configuration File

The CLI stores configuration in ~/.secrethub/config.toml:

server_url = "https://secrethub.example.com"
default_format = "table"

[auth]
token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
expires_at = "2024-12-31T23:59:59Z"

You can edit this file directly or use the config commands.

Environment Variables

Example:

export SECRETHUB_SERVER=https://secrethub.example.com
export SECRETHUB_FORMAT=json
secrethub secret list

Examples

Complete Workflow

# Login
secrethub login --role-id abc123 --secret-id xyz789

# Create a secret
secrethub secret create prod.db.password --value "secure-password-123"

# Get the secret
secrethub secret get prod.db.password

# Update the secret
secrethub secret update prod.db.password --value "new-password-456"

# View version history
secrethub secret versions prod.db.password

# Rollback to previous version
secrethub secret rollback prod.db.password 1

# Create a policy
secrethub policy create --from-template read_only --name "Developers"

# List agents
secrethub agent list

# Logout
secrethub logout

Using with Scripts

#!/bin/bash

# Get database password for automation
DB_PASSWORD=$(secrethub secret get prod.db.password --format json | jq -r '.value')

# Use in connection string
psql "postgresql://user:${DB_PASSWORD}@localhost/mydb"

Pipeline Integration

# In CI/CD pipeline
export SECRETHUB_TOKEN="${CI_SECRETHUB_TOKEN}"
API_KEY=$(secrethub secret get prod.api.key --quiet --format json | jq -r '.value')
echo "::set-output name=api_key::${API_KEY}"

Development

Building from Source

# Get dependencies
mix deps.get

# Build escript
mix escript.build

# Test the CLI
./secrethub --help

Running Tests

mix test

Generating Completions

During development, you can generate completion scripts using the Mix task:

# Generate both Bash and Zsh completions
mix cli.gen.completion all

# Generate only Bash completion
mix cli.gen.completion bash

# Generate only Zsh completion
mix cli.gen.completion zsh

Completion scripts are generated in apps/secrethub_cli/priv/completion/.

Support

License

Copyright © 2024 SecretHub. All rights reserved.