keybin-cli 0.1

Safe CLI password generator and manager. Encrypt your data, manage multiple profiles and more.

Keybin

Your secure, local and private password manager. Right in your terminal.

Built to be secure and efficient 🔑.

If you like the project, support me with a star and a follow on GitHub.

---

Table of Contents

• Keybin
• Table of Contents
• Features
• Installation
• Getting Started
• Detailed Usage
  • Main Commands
  • Profile Management (profile)
  • Log Management (log)
• License

Features

• 👥 Profile Management: Create multiple, independent profiles (e.g., for personal and work use) protected by a master password. Your data stays completely separate and secure.
• 📊 Status and session check: See which profile is currently active, how much time you've got left in session, log count and the current profile's security level.
• 🛡️ Security First: No passwords stored, not even hashed. Your masterkey is used to securely encrypt and decrypt a unique encryption key for each profile, ensuring only you can access your data.
• 🎲 Secure Password Generator: Create strong passwords, customizable in length and symbol usage.
• 🗄️ Robust Log Management: Safely add, find, and manage your sensitive data. Every operation is atomic, writing to a portable JSON file to prevent data corruption.
• 🔍 Intelligent Search: Search by exact fields and a powerful fuzzy search to find what you need even if you make a typo.
• 🏷️ Tag-based Organization: Add tags to your logs to filter and organize them your way.
• ✨ Modern Interface: Built with Typer and Rich for a clean and pleasant user experience.
• 🌐 Cross-Platform: Works on Linux, Windows, and MacOS, storing data in standard user directories for each OS.

Installation

You need Python 3.9+ and pip installed on your system.

Option A: Install from PyPI (Recommended)

The easiest way to install keybin is directly from the Python Package Index (PyPI).

For command-line tools like this, it is highly recommended to use pipx to install them in an isolated environment. This avoids dependency conflicts with other Python projects.

1. Install pipx (if you don't have it already):

   python3 -m pip install --user pipx
   python3 -m pipx ensurepath
   

   (You may need to restart your terminal after this step)

2. Install keybin using pipx:

   pipx install keybin-cli
   

   If you prefer to use pip, you can install it directly:

   pip install keybin-cli
   

3. Verify the installation: After installation, you can verify that keybin is working correctly.

   keybin --version
   

Option B: Install from Source (For Developers)

If you want to contribute to the project or use the latest development version, you can install it from the source code.

1. Clone the repository:

   git clone https://github.com/jotaesee/keybin.git
   
   cd keybin
   

2. (Recommended) Create and activate a virtual environment:

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   

3. Install in editable mode: This will install the package, but any changes you make to the source code will be immediately effective.

   pip install -e .
   

Getting Started

Getting started with keybin is fast and intuitive. Here's a typical workflow for a first-time user to set up their secure vault.

1. Create Your First Profile

First, you'll need to create a profile. Think of a profile as your personal encrypted vault. You'll protect it with a strong master password. You only set a profile once, but you can have multiple profiles. You could also use the default one, but remember, profiles with no masterkey are not encrypted!

# We'll use "profile add" to create a profile named "myprofile" with a master password
keybin profile add --user myprofile --key "your-very-strong-master-password"

Security Tip: You can create profiles without a masterkey, but a profile not secured does not encrypt it's logs.

2. Log In to Your Profile

To start using a profile, you need to log into it. If the profile's secured, you'll need to provide your masterkey to login.

# If the selected profile is encrypted, keybin will prompt for your masterkey.
keybin login myprofile

Tip: You can check your current session status at any time with keybin status.

3. Add Your First Password Log

Once you're logged in, you can add your first entry. For the most user-friendly experience, simply run the add command, and keybin will guide you.

# This will prompt you for all the necessary info (service, user, password, etc.).
keybin log add

You could also just use flags for a faster experience:

# --autopass will auto generate a new secure password.
keybin log add -s "GitHub" -u "jotaesee" --autopass -t dev -t personal

Pro Tip: Leave fields empty using --no-prompts or -n, this flag will skip missing info, and log it as you say.

4. Check your logs

Now, let's verify that your log was saved correctly. Use the find command to search your vault.

# A fuzzy search for "git" will find the "GitHub" log we just created.
keybin log find git

You could pair this fuzzy search with filters like email, service, tags and username, or direcly search a log by it's id. You can also see all logs in the current profile by running keybin log find all.

5. Log Out of Your Profile

When you're finished, it's good practice to log out. This locks your vault, ensuring your data is secure until you log in again.

# The logout command ends the session, so secured commands are not accesible.
keybin logout

Pro-Tip: If you are already logged into a profile and want to change to another one without logging out first, you can use the "keybin profile switch <other_profile>" command.

Detailed Usage

This section provides a detailed breakdown of all available commands and their options.

Most data-related commands (like adding or finding logs) require an active, logged-in session. You can check your current session with keybin status.

---

Main Commands

These are the top-level commands available directly under keybin.

login

Logs into a profile to start a secure session. This unlocks the vault, allowing you to use session-secured commands.

Usage:

keybin login <USER> [KEY]

Arguments:

USER: The name of the profile you want to log into.

KEY (Optional): The masterkey for the profile. If the profile is encrypted and the key is not provided, you will be prompted to enter it securely.

Example:

# Log into the 'personal' profile. It will prompt for the password.
keybin login personal

logout

Logs out of the current profile, ending the secure session and locking the vault.

Usage:

keybin logout

status

Displays a summary of the current session, including the active profile, its encryption status, the path to its data file, the number of saved logs, and the time remaining in the current session.

Usage:

keybin status

genpass

Generates a new, secure password. Also available via the alias gp.

Usage:

keybin genpass [OPTIONS]

Options:

-l, --length <INTEGER>: The desired length for the new password (default: 16).

--no-symbols / --symbols: Include or exclude symbols in the generated password (default: include symbols).

-c, --copy: If set, copies the new password directly to the clipboard.

Example:

# Generate a 24-character password and copy it to the clipboard
keybin genpass -l 24 -c

Profile Management (profile)

Commands for creating, viewing, and managing your user profiles.

profile add

Creates a new profile. If options are not provided, it will guide you through an interactive setup.

Usage:

keybin profile add [OPTIONS]

Options:

-u, --user <TEXT>: The name for the new profile.

-k, --key <TEXT>: The masterkey to encrypt the profile's data (recommended).

-p, --path <TEXT>: A custom file path to store the profile's data.

Example:

# Create a new encrypted profile named "work"
keybin profile add --user work --key "my-secret-work-password"

profile list

Displays a table with all your existing profiles, their data paths, and whether they are encrypted.

Usage:

keybin profile list

profile switch

Switches from one logged-in profile to another without needing to log out first. Requires an active session.

Usage:

keybin profile switch <USER> [KEY]

Arguments:

USER: The name of the profile you want to switch to.

KEY (Optional): The masterkey for the target profile. You will be prompted if it's required.

profile delete

Permanently deletes a profile and all of its associated data.

Usage:

keybin profile delete <PROFILE>

Warning: This action is irreversible. For encrypted profiles, you will be prompted for the masterkey to confirm the deletion.

Log Management (log)

Commands for adding, finding, and deleting logs (entries) within the currently active profile. These commands require a logged-in session.

log add

Adds a new password log to the active vault. You can provide info via flags or let the command prompt you for any missing fields.

Usage:

keybin log add [OPTIONS]

Options:

-s, --service <TEXT>: The name of the service (e.g., Google, GitHub).

-u, --user <TEXT>: Your username for the service.

-e, --email <TEXT>: Your email for the service.

-p, --password <TEXT>: The password to save.

-t, --tags <TEXT>: Add one or more tags for organization (e.g., -t work -t dev).

-a, --autopass: Automatically generates a secure password for this log.

-n, --no-prompts: Skips interactive prompts for missing information.

log find

Searches for logs in the active vault. Running keybin log find will perform a fuzzy search.

Usage:

keybin log find [SEARCH] [OPTIONS]

Options:

-i, --id <INTEGER>: Search for a log by its exact ID.

-s, --service <TEXT>: Filter by exact service name.

-u, --user <TEXT>: Filter by exact username.

-e, --email <TEXT>: Filter by exact email.

-t, --tags <TEXT>: Filter for logs that contain all specified tags.

Examples:

# Fuzzy search for any logs related to "google"
keybin log find google

# Find all logs with the "work" tag for the "GitHub" service
keybin log find --service "GitHub" -t work

log delete

Deletes a specific log from the vault using its ID.

Usage:

keybin log delete <ID> [OPTIONS]

Tip: Not sure what the ID is? Run keybin log find all to see a list of all your logs.

Options:

-n, --no-prompt: If set, deletes the log without asking for confirmation.

Example:

# Delete the log with ID 15 after showing a confirmation prompt
keybin log delete 15

License

MIT