Skip to content

Command-line Parameters

This page contains the full list of commands with parameters that handle interacting with secrets through PigeonHole.

The following commands are the parent commands that manage their respective resources.

Command Description Shorthand
auth Used to log into PigeonHole ---
login This is an alias to auth login ---
secret Used to manage secrets secret, secrets, s
me Show remote user info incl. keys ---
key Manage keys key, keys
version Dump build info ---

Auth Commands

The following listed commands are the sub-commands to be used with the auth parent command.

Command Description Shorthand
login Initiates the Authentication Flow ---
list-providers List remotely available secrets ---

List Providers

This command has no parameters.

Examples

List Providers Examples

pigeonhole auth list-providers

IdP Login

Paramater Description Shorthand Default
--provider This overrides the Default Identity Provider as configured at the server-side. --- ---
IdP Login Examples

Login with specific Identity Provider

Use list-providers to find the available Identity Providers to supply to --provider.

pigeonhole auth login --provider github

Secret Commands

Below are the subcommands used with pigeonhole secret.

Command Description Shorthand
send Send a PigeonHole secret post, send, drop, ship, s, p
list List remotely available secrets list, l, ls
retrieve Retrieve a PigeonHole secret retrieve, r, download, get, g, fetch, f
delete Delete sent secrets delete, del, rm, d
count Count the number of available secrets ---

Send Parameters

Parameter Description Shorthand Default
--recipient The email address of the recipient you want to post a secret to. -r ---
--filepath The path of the file or folder that is desired. -f ---
--expiry The time duration until the secret expires -x 7d
--use-ephemeral-keys This is an opt-in feature to leverage Tranisent Keys -e false
--one-time-secret Changes default behaviour to delete the secret on recipient download -1 false
Send Examples
Send Simple Secret

This is the simplest example of how to send a file or folder. 

pigeonhole secret send --recipient john.doe@pigeono.io --filepath ./myfile

Send One Time Secret

This is an example of the One-Time-Secret functionality that will ensure the secret can only be downloaded once by the recipient. 

pigeonhole secret send -1 --recipient john.doe@pigeono.io --filepath ./myfile

Pipe Content (stdin) Secret

A more advanced example where PigeonHole will consume content from stdin and send it as part of the normal secure method. 

cat /etc/hosts | pigeonhole secret send --recipient john.doe@pigeono.io

Retrive Parameters

Parameter Description Shorthand Default
--filepath The output path of where to decrypt and write the secret -f
--reference The id or part reference of the secret -r ---
Retrieve Examples
Retrieve a Basic Secret

This is the simplest way to retrieve a secret. The secret gets decrypted to a path relative to the current working directory. 

pigeonhole secret retrieve --reference shiny-whale

Writes the file or folder to ./decrypted/<reference>/<output>

Delete Parameters

Parameter Description Shorthand Default
--reference The id or part reference of the secret -r ---
--all Deletes all secrets -a ---
Delete Examples
Delete Secret by Reference 
pigeonhole secret delete --reference shiny-whale
Delete Secret by Glob

This example glob matches so the pattern *shiny* 

pigeonhole secret delete --reference shiny

List Parameters

Parameter Description Shorthand Default
--reference The id or part reference of the secret -r ---
--all List all sent and received secrets (default is just received) -a ---
List Examples
List Secrets 
pigeonhole secret ls
Find Secrets by Ref

The following will return all secrets that match the glob pattern *shiny* associated with the user.

pigeonhole secret list --reference shiny

Count Parameters

This command has no sub-command nor parameters.

Me Commands

Command Description Shorthand Default
show Dumps the remotely held information about the user --- ---

Show Parameters

This command has no sub-command nor parameters.

Key Commands

Command Description Shorthand Default
list Dumps the remotely held keys created by the user list, l, ls ---

Version Commands

This command has no sub-command nor parameters.