Kipas CLI

Command-line interface for Kipas.

Installation

pnpm install
pnpm build

Usage

Repository Management

Initialize Repository

kipas init <git-url>

Initializes a new repository or connects to an existing one. If the repository is already initialized, it will connect using your local keys.

View Repository Info

kipas info

Displays current repository information including URL, ID, and current user.

Sync Repository

kipas sync

Pulls the latest changes from the remote repository.

User Management

Backing up your keys

Create a backup of your keys (encrypted by default, or plain JSON with a warning). After kipas init, you may be prompted to create a backup; you can also run these commands anytime.

# Encrypted backup (default) – you will be prompted for a password
kipas backup-keys --output backup.enc

# Plain JSON backup (store the file securely, e.g. encrypted drive)
kipas backup-keys --output backup.json --no-encrypt

# Overwrite existing file without prompting
kipas backup-keys --output backup.enc --force

# Restore from backup
kipas restore-keys --input backup.enc
kipas restore-keys --input backup.json --force

Alternative: You can manually copy ~/.kipas/keys.json to a secure location and restore by copying it back. Prefer backup-keys / restore-keys for password-protected backups.

Add User

Add a new user to the repository:

# Using base64 verification package
kipas user add <email> --verification-package <base64>

List Users

kipas user list

Lists all users in the repository.

Vault Management

Create Vault

# Interactive mode
kipas vault create

# With flags
kipas vault create --name "Personal" --description "My passwords"

List Vaults

kipas vault list

Lists all vaults you have access to.

View Vault Info

kipas vault info <vault-id>

Displays detailed information about a vault including members.

Share Vault

kipas vault share <vault-id> <email>

Shares a vault with another user. The user must already be added to the repository.

List Vault Members

kipas vault members <vault-id>

Lists all members of a vault.

Account Management

Add Account

# Interactive mode
kipas account add <vault-id>

# With flags
kipas account add <vault-id> \
  --name "GitHub" \
  --username "[email protected]" \
  --password "secret123" \
  --url "https://github.com" \
  --tags "work,dev" \
  --notes "My work account" \
  --otp "JBSWY3DPEHPK3PXP"

List Accounts

kipas account list <vault-id>

Lists all accounts in a vault.

Get Account

# Show account (password hidden)
kipas account get <account-id>

# Show password
kipas account get <account-id> --show-password

# Copy password to clipboard
kipas account get <account-id> --copy-password

Search Accounts

# Search by name or ID
kipas account search <query>

# Filter by tag
kipas account search <query> --tag work

Update Account

# Update password
kipas account update <account-id> --password "newpassword"

# Update multiple fields
kipas account update <account-id> \
  --name "New Name" \
  --username "[email protected]" \
  --password "newpassword" \
  --url "https://newsite.com" \
  --tags "work,updated" \
  --notes "Updated notes" \
  --otp "JBSWY3DPEHPK3PXP"

# Remove OTP (use empty string)
kipas account update <account-id> --otp ""

Note: Only specified fields are updated. Unspecified fields remain unchanged. The account data is re-encrypted with a new nonce and re-signed for security. The vault ID is automatically determined from the account ID.

Delete Account

kipas account delete <account-id>

Deletes an account. The vault ID is automatically determined from the account ID.

Audit

View Audit Log

# View all audit entries
kipas audit log

# Filter by vault
kipas audit log --vault <vault-id>

Export Audit Log

# Export to default file (audit-export.json)
kipas audit export

# Export to specific file
kipas audit export --output audit.json

Configuration

Show Configuration

kipas config show

Displays current configuration including repository settings and session timeout.

Set Configuration

# Set session timeout (in seconds)
kipas config set session-timeout 1800

Architecture

The CLI is built with a modular architecture to support future web expansion:

• Service Modules: Core business logic is separated into reusable service modules:

  • user-service.ts - User management operations
  • vault-service.ts - Vault management operations
  • account-service.ts - Account management operations
  • session-service.ts - Session management

• CLI Layer: The CLI (cli.ts) acts as a thin layer that:

  • Parses command-line arguments
  • Calls service functions
  • Handles I/O and user interaction
  • Manages git operations
  • Integrates session checks

This architecture allows the same service functions to be reused in a future web interface.

Testing

Run tests:

pnpm test

Run tests with coverage:

pnpm test -- --coverage

Development

Build the project:

pnpm build

Watch mode:

pnpm dev

Security Notes

• All sensitive data (passwords, keys) are cleared from memory after use
• Keys are cached in memory for 15 minutes after access (configurable)
  • Each command execution updates the timestamp
• All operations are cryptographically signed and verified
• Audit logs provide tamper-proof history of all operations

See Also

• Kipas Specification - Complete specification document
• Core Package - Core business logic
• Crypto Package - Cryptographic primitives