package passage
Install
Dune Dependency
Authors
Maintainers
Sources
sha256=36c7c211f44c3e2ce070187c598a2586245c022a1f192ed3785e1816627f7f11
sha512=63add75ff3b704abf628ad3c34aef9ad60aa340f895dfbae519eefa4f3dd3ccce3a145f2364b23d74031f2f414aca6991cf810b9b5636641a0207bebe81b9f8d
README.md.html
Passage
passage
- store and manage access to shared secrets
Installation
apt install age
opam install . --deps-only
Development
Building the project
make build
Running tests
make test
Secret format
Multi-line secrets with comments:
<empty line>
possibly several lines of comments
without empty lines
<empty line>
secret until end of file
Multi-line secrets without comments:
<empty line>
<empty line>
secret until end of file
Single-line secrets with comments:
single-line secret
<empty line>
comments until end of file
Single-line secrets without comments:
single-line secret
The rationale for why we have 2 distinct secret formats for multi-line and single-line secrets (and not just multi-line secrets) is mainly for backward compatibility reasons since most of the existing secrets are of the "single-line secret" format.
Commands
Reading secrets
passage get [-c, --clip] [-l, --line=LINE] [-q, --qrcode] [-s, --singleline] SECRET_NAME
Outputs the content of the text of the secret in
SECRET_NAME
, excluding comments
passage secret [-c, --clip] [-l, --line=LINE] [-q, --qrcode] [-s, --singleline] SECRET_NAME
An alias of
passage get
passage cat [-c, --clip] [-l, --line=LINE] [-q, --qrcode] SECRET_NAME
Outputs the whole content of the secret in
SECRET_NAME
, including comments
passage show SECRET_NAME
Outputs the whole content of the secret in
SECRET_NAME
, including comments. Behaves differently when used with PATHs, please check below.
Templating with secrets
passage template TEMPLATE_FILE [TARGET_FILE]
Generates
TARGET_FILE
by substituting all secrets inTEMPLATE_FILE
Secrets in
TEMPLATE_FILE
are denoted with the following format{{{subdir/secret_name}}}
. In particular, note the following:Three opening and closing braces
No leading and trailing whitespaces before and after
secret_name
secret_name
must start with an alphanumeric character (either lowercase or uppercase), followed by 0 or more alphanumeric characters, underscores, hyphens, slashes, or dots (reference: template_lexer.ml)
Example when substituting a single-line secret:
$ cat template_file { "non_secret_config1": "hello", "sendgrid_api_key": "{{{sendgrid_api_key}}}", "non_secret_config2": "bye", } $ passage get sendgrid_api_key thesupersecretkey the above is the sendgrid api key! $ passage template template_file { "non_secret_config1": "hello", "sendgrid_api_key": "thesupersecretkey", "non_secret_config2": "bye", }
Example when substituting a multi-line secret:
$ cat template_file foo{{{multiline_secret}}}bar $ passage get multiline_secret comment_line 1 comment_line 2 secret_line 1 secret_line 2 $ passage template template_file target_file $ cat target_file foosecret_line 1 secret_line 2bar
passage subst [TEMPLATE_ARG]
similar to passage template, but you pass in a string template and the result is output to stdout
$ passage secret test/secret unbelievable stuff $ passage subst "This secret is {{{test/secret}}}" This secret is unbelievable stuff
passage template-secrets [TEMPLATE_FILE]
returns a list of sorted secrets identified in that template file per the parse format
secrets are not checked for existence
Specifying recipients
Secrets' recipients are specified in the .keys
file in the immediately containing folder. The first time a folder is used, passage will create this file. If no recipients are specified, it falls back to the caller as the sole recipient based on the file referenced by $PASSAGE_IDENTITY
.
Recipients are not inherited from containing (parent) folders. Recipients in a folder can only be increased when added by the existing recipients.
All secrets in a given folder must share the same set of recipients.
passage edit-who SECRET_NAME
edit the recipients for the specified secret (and path).
Creating or updating secrets
passage new SECRET_NAME
Interactive secret creation using
$EDITOR
and prompts.Can only be used in interactive shell
passage create SECRET_NAME
Creates a secret using contents from standard input. Use Ctrl+d twice to signal end of input.
Can pipe from another command into
passage create
. E.g.:
$ echo "secret" | passage create secret_folder/secret
passage edit SECRET_NAME
Interactive editing of
SECRET_NAME
using$EDITOR
Can only be used in interactive shell
passage replace SECRET_NAME
Replaces
SECRET_NAME
's secret with the user input and keeps the comments. Use Ctrl+d twice to signal end of input.If you use
replace
on a secret that doesn't exist, it creates a new secret without comments (only in folders where the user is already a recipient)
passage rm [--force] [--verbose] SECRET_NAME / passage delete [--force] [--verbose] SECRET_NAME
Deletes
SECRET_NAME
pathIf
SECRET_NAME
is the only secret in that folder, passage deletes the whole folder
Managing secrets
passage list [PATH]
/ passage ls [PATH]
Recursively list all secrets in
PATH
passage search PATTERN [PATH]
List all secrets in
PATH
containing contents matchingPATTERN
passage show [PATH]
Recursively list all secrets in
PATH
in a tree-like formatWill work the same way as
cat
when used with secret names instead of a PATH. Doesn't take any arguments or flags
passage refresh [PATH]
Re-encrypts all secrets in
PATH
per the recipients in the corresponding .keys file
passage who [PATH]
List all recipients of secrets in
PATH
passage what RECIPIENT_NAME
List all secrets that
RECIPIENT_NAME
has access to
Environment Variables
PASSAGE_DIR
Overrides the default
passage
directory.
PASSAGE_KEYS
Overrides the default
passage
keys directory.
PASSAGE_SECRETS
Overrides the default
passage
secrets directory.
PASSAGE_IDENTITY
Overrides the default identity
.key
file that will be used bypassage
PASSAGE_X_SELECTION
Overrides the default X selection to use when clipping to clipboard. Allowed values are
primary
,secondary
, orclipboard
(default).
PASSAGE_CLIP_TIME
Overrides the default clip time. Specified in seconds.
Utilities
passage healthcheck
checks for issues with secrets, and for directories without
.keys
file
passage realpath [--verbose] [PATH]
show the full filesystem path to secrets/folders