Token Manager

Store API tokens in named profiles and print them as shell exports. Each profile can keep tokens as plaintext JSON, or encrypt them with gpg or openssl.

The PyPI name is lupaxa-token-manager. The import path is lupaxa.token_manager. The console scripts are tokenctl and token-manager.

Install

pip install lupaxa-token-manager

Requires Python 3.10 or newer. Encryption modes need the gpg or openssl binary on PATH. Plaintext profiles do not.

Quick Start

tokenctl profile init
tokenctl add --type github --name main --value 'ghp_xxx' --env-var GITHUB_TOKEN
tokenctl list
source <(tokenctl set --type github --name main --format export)

A child process cannot change the parent shell, so source the export line. --profile goes before the subcommand and defaults to default:

source <(tokenctl --profile ci set --type github --name main --format export)

Names are unique within a type, so main can exist for both github and aws. Selecting by --name also needs --type. --id selects a token on its own. --env-var defaults to TYPE_TOKEN (for example GITHUB_TOKEN).

Command Reference

List and Show

tokenctl list
tokenctl list --type github --format names
tokenctl list --format json
tokenctl list --format json --reveal
tokenctl list --columns name,env_var,value --max-width 100
tokenctl types
tokenctl show --type github --name main
tokenctl show --type github --name main --reveal

The default list is a grouped text table. The table and JSON both hide secret values unless you pass --reveal. show does the same.

--columns picks and orders columns. The names are name, env_var, id, updated, created, value, and type. --max-width wraps the table to that many characters.

Add, Update, and Delete

tokenctl add --type pypi --name publish
printf '%s' 'pypi-secret' | tokenctl add --type pypi --name publish --value -
tokenctl update --type github --name main --new-name prod --value 'ghp_new'
tokenctl delete --type pypi --name publish

Omit --value on add and the tool prompts without echoing. --value - reads the secret from stdin, which keeps it out of shell history and the process list. On update, omit --value to leave the secret unchanged, or pass --value - to replace it from stdin.

Set

tokenctl set --type github --name prod --format export
tokenctl set --type pypi --name publish --format dotenv
tokenctl set --type github --name prod --format value

export is the default. Values are single-quoted for the shell.

Profiles

tokenctl profile init
tokenctl --profile ci profile init --encryption openssl
tokenctl --profile ci profile show
tokenctl --profile ci profile set-encryption gpg

set-encryption rewrites the tokens in the new mode and removes the previous token file, so a switch to encryption does not leave plaintext behind.

Migrate

tokenctl migrate --from-profile default --to-profile ci --dry-run
tokenctl migrate --from-profile default --to-profile ci --type github --name prod --move --overwrite

--dry-run prints the change and writes nothing. Without --move, the source profile is left as it is. --overwrite replaces a destination token that already uses the same type and name. A conflict without --overwrite is still an error during a dry run.

Storage and Encryption

Tokens live under $XDG_CONFIG_HOME/tokenctl (or ~/.config/tokenctl). Each profile is profiles/<profile>/ with a config.json encryption mode of none, gpg, or openssl.

Set TOKENCTL_PASSPHRASE for a non-interactive shell. On a terminal the tool prompts, and that passphrase is passed to gpg or openssl on its own pipe. It is not written into the environment. Files are written to a temporary path and then replaced.

Each token stores id, type, name, value, env_var, created_at, and updated_at. Timestamps are UTC in YYYY-MM-DDTHH:MM:SSZ form.

Exit 0 is success. Exit 1 is a runtime failure (missing token, conflict, or crypto error). Exit 2 is a usage error, such as --name without --type.

Library

from lupaxa.token_manager import Store

store = Store(profile="default")
for token in store.load():
    print(token.name, token.type)

Store(profile, config_dir=...) overrides the config root.

Documentation

Site pages live in mkdocs/ and publish to https://token-manager.thelupaxaproject.org/.

make init
make python-install-dev
make mkdocs-serve