Skip to content

Quick-Start Guide

PigeonHole is a simple command-line tool that posts secrets securely. While I was formualting the idea, I knew I wanted to build it from the grownd up to be intuitive and familiar to those who use modern command-line tooling and super easy to use.

Installation

Via Package Managers

brew tap pigeonholeio/pigeonhole
brew install pigeonholeio/pigeonhole/pigeonhole-cli

brew tap pigeonholeio/pigeonhole
brew install pigeonholeio/pigeonhole/pigeonhole-cli

Apt packages are distributed via our package mirror https://packages.pigeono.io.

Configure the Apt repo by;

sudo apt update && sudo apt install -y curl gnupg ca-certificates
curl -fsSL https://packages.pigeono.io/gpg.pub | sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/pigeonhole.gpg
echo "deb https://packages.pigeono.io/apt noble main" | sudo tee /etc/apt/sources.list.d/pigeonhole.list

Then install PigeonHole: 

sudo apt update && sudo apt install pigeonhole-cli

Yum packages are distributed via our package mirror https://packages.pigeono.io.

Configure the Yum repo by; 

sudo rpm --import https://packages.pigeono.io/gpg.asc
sudo tee /etc/yum.repos.d/pigeonhole.repo <<EOF
[pigeonhole]
name=PigeonHole Repository
baseurl=https://packages.pigeono.io/rpm/
enabled=1
gpgcheck=1
gpgkey=https://packages.pigeono.io/gpg.asc
EOF
Then install PigeonHole: 
sudo dnf install -y pigeonhole-cli
# or
sudo yum install -y pigeonhole-cli

CLI Auto-Completion Script

It's handy to have the shell auto-completion installed for your shell to make using cli tools easier.
To find out what shells are supported, run the following in your terminal.

pigeonhole completion

Then run the command relevant for your shell e.g. Take ZSH as an example. Add the completion script output to your ZSH Profile: 

pigeonhole completion zsh >> ~/.zshrc
source ~/.zshrd

Coming Soon. The Windows binary is available on the Releases page.

Coming Soon!!

Manual Install with Release Binaries

You can obtain the binaries for your platform and architecture by visiting Releases.

  1. Visit the Releases page, find the latest release and download the binary for your architecture
  2. Place the binary in a location that is in your $PATH environment variable
  3. You should now be able to run pigeonhole login from the command-line

PigeonHole Authentication

Authenticication is handled completely by the OpenID Connect protocol with your Identity Provider. You must have a validated email address associated with your Identity Provider or third party service.

Tip - Request a new Identity Provider Support

Only Microsoft, Github and Gitlab are currently supported. Raise a [FEATURE REQUEST] Identity Provider GitHub issue to add support for your Identity Provider.

List Supported Identity Providers

To find the list supported Identity Providers

Signing in

To initiate the authentication flow, run;

The default Identity Provider will be shown with a green tick when running pigeonhole auth list-providers command

pigeonhole login

The following command will list the supported list of Identity Providers;

pigeonhole auth list-providers
Now you can use pass your preferred Identity Provider into the login command as follows;

pigeonhole login --provider github

Follow the prompts to sign in and the PigeonHole command-line tool will automatically generate keys for you to get you ready to send your first secret!

Send your first Secret

Simply, specify the recipient and filepath and that's it! No complicated gpg commands to encrypt or decrypt, all that is handled for you.

    pigeonhole secret send --recipient user@domain.com --filepath ./myfile

That's it!

Retrieving a Secret

List Received Secrtes

To find a list of secrets you've been sent use the secret list command;

pigeonhole secret list

Once you know the secret reference of the secret you want to retrieve;

    pigeonhole secret collect --reference <reference>

You can also use the --filepath to override the path used to decrypt and extract your secret.

Next Steps

Take a look at Managing Secrets to find out more about managing secretes like;

  • Sending One-Time Secrets
  • Secure file shredding
  • Sending Secrets with a custom expiry
  • Deleting Secrets
  • Send and pipe from stdin