AxKeyStore

AxKeyStore is a secure, open-source command-line interface (CLI) tool designed to manage your secrets, keys, and passwords. It leverages your own private GitHub repository as the secure storage backend, ensuring your data is accessible, versioned, and under your control. Data travels encrypted over the wire and is stored encrypted in the remote repository. No secrets are ever stored in plain text in the remote repository. Also, no secrets are ever stored in the local filesystem or on any other remote server.

AxKeyStore is an Open Source Project built by Appxiom Team Visit https://www.appxiom.com to know more about us. You will love our product if you are into software engineering!

MIT License

1. Introduction
- Security First (Zero Trust)
- Features
2. How to use
- Installation
- Usage
  - Interactive Terminal UI (TUI)
  - Command Line Interface (CLI)
3. For developers
License

1. Introduction

Security First (Zero Trust)

AxKeyStore is built on a Zero Trust architecture with a robust multi-layered encryption scheme:

Local Master Key (LMK): A 36-character random alphanumeric string generated uniquely for each profile and stored on your local machine.
- Purpose: Encrypts your sensitive local configuration, including your GitHub access token and the name of your private repository.
- Security: The LMK itself is encrypted with the user's Master Password using Argon2id and XChaCha20-Poly1305.
Remote Master Key (RMK): A 36-character random alphanumeric string generated uniquely for your vault and stored on GitHub.
- Purpose: Encrypts the actual secrets (keys/passwords) stored in your repository.
- Security: The RMK is encrypted with the user's Master Password (via client-side encryption) before being uploaded to GitHub.
Three-Layer Encryption:
1. Secrets are encrypted using the RMK.
2. RMK is encrypted using your Master Password and stored on GitHub.
3. Local Credentials (Token/Repo Name) are encrypted using the LMK, which is also secured by your Master Password.
Client-Side Encryption: All encryption happens purely on your machine. No plain-text secrets, master keys, or passwords ever touch the network or are stored unencrypted on disk.
Untrusted Storage: GitHub is treated as untrusted cloud storage. It only ever sees encrypted binary blobs.
Secure Algorithms: Uses modern, authenticated encryption standards (XChaCha20-Poly1305) and robust key derivation (Argon2id).

Features

GitHub Storage: Utilizes a private repository on your GitHub account or an organization for free, reliable, and versioned cloud storage.
Unified Auth: Authenticates securely using GitHub Apps and the Device Flow.
Installation Management: Simple one-time installation to grant access to specific repositories.
Simple CLI: Easy-to-use commands to store and retrieve your credentials.
Category Organization: Organize your secrets in hierarchical categories (e.g., api/production/internal).
Multi-Profile Support: Manage multiple vaults with different logins, master passwords, and GitHub repositories.

2. How to use

Installation

macOS / Linux

To install on macOS or Linux, run:

curl -sSL https://raw.githubusercontent.com/basilgregory/axkeystore/main/install.sh | bash

To install a specific version on macOS or Linux, run:

curl -sSL https://raw.githubusercontent.com/basilgregory/axkeystore/main/install.sh | bash -s v0.1.6

Windows

To install on Windows, run the following command in PowerShell:

powershell -c "irm https://raw.githubusercontent.com/basilgregory/axkeystore/main/install.ps1 | iex"

To install a specific version on Windows, run:

powershell -c "irm https://raw.githubusercontent.com/basilgregory/axkeystore/main/install.ps1 | iex -s v0.1.6"

The scripts will download the appropriate binary, move it to $HOME/.axkeystore/bin, and automatically configure your PATH.

Usage

Interactive Terminal UI (TUI)

The easiest way to interact with AxKeyStore is through the Terminal User Interface. Simply run the command without any arguments:

axkeystore

This will launch an interactive vault explorer where you can:

Watch progress: View real-time loading screens while the CLI authenticates and downloads your keys.
Navigate: Move through categories and keys using your arrow keys.
Read & Decrypt: View decrypted secrets in real-time.
Add: Press a to add a new key directly from the TUI. You will be prompted for an optional category, key name, and the secure value.
Manage Profiles: Press p to open the Profile Selection screen.
- Switch to any existing profile seamlessly by selecting it and entering its master password.
- Press c to Create and Initialize a completely new profile and repository inline.
- Press d to securely Delete an unused profile.
Exit: Press q or Esc to exit.

Command Line Interface (CLI)

Login: Authenticate with your GitHub account.
```
axkeystore login
```
Note: During your first login, you will be prompted to set a Master Password. This password is used to encrypt your sensitive GitHub access token locally on your machine.

GitHub App Installation: After logging in, the CLI will provide a link to install the app on your GitHub account or organization: https://github.com/apps/<app-name>/installations/new. You must install the app to grant it access to your repositories.
Initialize: Set up a repository for storage (if not already done).
```
# Use a repo in your account
axkeystore init --repo my-secret-store

# Or specify an organization/owner
axkeystore init --repo my-org/my-secret-store
```
Note: If the repository already exists and has been initialized previously (e.g., on another machine), AxKeyStore will prompt for your Master Password to verify access. You must provide the correct password associated with that repository to proceed.
Store a Secret: Encrypt and upload a key/password.
```
axkeystore store --key "my-api-key" --value "super_secret_value"
```
Note: You must run axkeystore init before storing or retrieving any keys. If the repository is not configured, you will be prompted to do so. You must enter your Master Password for every operation to unlock your local session and vault.
Auto-Generate a Secret: If you don't provide a value, AxKeyStore will generate a secure random alphanumeric value (6-36 characters) for you.
```
axkeystore store --key "my-api-key"
```
You'll see the generated value and be asked to confirm before storing:
```
Generated value: qOmH8qHQ3pnuASPrho662Mqd
   (Length: 24 characters)

Do you want to use this generated value? (y/n):
```
Retrieve a Secret: Download and decrypt a key.
```
axkeystore get "my-api-key"
```

List All Secrets: List all stored keys with their decrypted values, grouped by category.

axkeystore list

Output is displayed as name-value pairs grouped by category:

Stored Keys for profile 'default'

[cloud/aws/production]
  aws-key     = AKIAIOSFODNN7EXAMPLE
  aws-secret  = wJalrXUtnFEMI/K7MDENG

(uncategorized)
  api-token   = ghp_abc123...

Tip: Use --profile to list keys from a specific profile:
axkeystore --profile "work" list

View Version History: List previous versions of a key (10 at a time).
```
axkeystore history "my-api-key"
```
This will show a table with the SHA, date, and commit message for each version.
Retrieve a Specific Version: Use the SHA from history to retrieve a previous value.
```
axkeystore get "my-api-key" --version <SHA>
```

Store with Category: Organize secrets in hierarchical categories.

axkeystore store --key "aws-key" --value "AKIAIOSFODNN7EXAMPLE" --category "cloud/aws/production"

Tip: You can also auto-generate values with categories:
axkeystore store --key "aws-key" --category "cloud/aws/production"

Retrieve from Category: Retrieve a secret from a specific category.

axkeystore get "aws-key" --category "cloud/aws/production"

Delete a Secret: Delete a stored key (with confirmation prompt).
```
axkeystore delete "my-api-key"
```

Delete from Category: Delete a secret from a specific category.

axkeystore delete "aws-key" --category "cloud/aws/production"

Reset Master Password: Update your master password safely.
```
axkeystore reset-password
```
Note: This command is profile-aware; it only resets the password for the currently active profile (or the one specified via --profile). The process safely re-encrypts both your Local Master Key and your Remote Master Key with the new password. It is transactional: it updates the remote key on GitHub first, and only on success does it update the local configuration.
Manage Profiles: AxKeyStore supports multiple profiles, each with its own master p

Axkeystore

Install / Use

README