Back to site
CommandChronicles logoCommandChronicles

Frequently Asked Questions

Everything you need to know about CommandChronicles

Loading...Complete Guide

How it Works

How does CommandChronicles capture my commands?

CommandChronicles uses shell integration hooks that automatically capture commands as you execute them. Here's how it works:

1
Shell Hooks Installation
When you run ccr install-hooks, the CLI generates shell-specific hook scripts for bash or zsh
2
Automatic Capture
The hooks intercept commands before and after execution, capturing comprehensive metadata
3
Background Recording
Commands are encrypted and stored locally in real-time using the ccr record command
4
Session Management
Each shell session gets a unique ID to organize your command history

The capture process is completely transparent - you don't need to do anything once the hooks are installed.

What data does it capture?

The hooks intercept your commands and capture:

  • • The actual command text
  • • Exit code (success/failure)
  • • Execution duration
  • • Working directory
  • • Git repository information (if applicable)
  • • Timestamp and session information
  • • Hostname and user
  • • Shell type
  • • Environment variables
  • • Git branch and commit (when in repo)

Shell Integration

How do I install shell hooks?

After installing CommandChronicles, set up shell integration:

ccr install-hooks

Then restart your shell. CommandChronicles will automatically detect your shell type (bash/zsh) and install the appropriate hooks.

Can I uninstall the hooks?

Yes, you can temporarily or permanently disable command capture:

ccr uninstall-hooks

Information & Help

Additional TUI Features

  • Tab - View detailed command information (duration, directory, git info)
  • Ctrl+T - View command statistics
  • ? - Show help and all available keybindings

Important Note: Command injection (Enter/Ctrl+J) only works when the TUI is launched via Ctrl+R after installing shell hooks. Running ccr tui directly will show the interface but cannot inject commands into your shell.

Tag System

How do I organize commands with tags?

Tags are short labels that help categorize your commands. You can add tags manually or let CommandChronicles automatically tag commands based on patterns.

Manual Tagging

  • ccr tag add 123 deployment
  • ccr tag add 123 production
  • ccr tag search docker
  • ccr tag list

Auto-Tagging

  • docker commands → docker tag
  • git commands → git tag
  • kubectl commands → k8s tag
  • npm/yarn commands → nodejs tag

How do I use tags in the TUI?

The TUI provides visual tag management with colored labels and keyboard shortcuts:

Keyboard Shortcuts

  • Ctrl+G - Manage tags for selected command
  • Ctrl+F+G - Toggle tag search mode
  • Ctrl+T - Access color picker for tags
  • Ctrl+A - Manage auto-tag rules

Visual Features

  • • Colored tag labels for easy identification
  • • Up to 5 tags per command
  • • 16 color palette for customization
  • • Filter commands by tag combinations

Notes System

How do I add notes to commands?

Notes let you add context and explanations to commands, turning your history into a personal knowledge base. You can add up to 1000 characters per note.

CLI Note Management

  • ccr note add 123 "Deploy to production server"
  • ccr note edit 123 "Updated deployment process"
  • ccr note show 123
  • ccr note search "deployment"

TUI Note Features

  • Ctrl+N - Edit note for selected command
  • Ctrl+F+N - Search commands and notes together
  • Tab - View command details including notes
  • Commands with notes show a colored dot (●) indicator

What should I include in my notes?

Good notes transform your command history into a valuable reference. Here's what to include:

Context & Purpose

  • • Why did you run this command?
  • • What problem did it solve?
  • • Which environment/server was it for?
  • • What were the important parameters?

Technical Details

  • • Explanation of complex flags or options
  • • Links to documentation or tickets
  • • Prerequisites or dependencies
  • • Expected outcomes or side effects

Example: For kubectl apply -f deployment.yaml --namespace=production
Note: "Deployed v2.1.0 to production cluster. Includes security patches and performance improvements. Remember to check pod status after deployment."

Security & Privacy

Is my command history secure?

Yes, CommandChronicles implements military-grade security:

  • • Local-Only Storage: All data is stored locally on your machine - no cloud services or telemetry
  • • Full Encryption: Every command is encrypted using XChaCha20-Poly1305 before storage
  • • Secure Authentication: Password-based access with Argon2id key derivation
  • • Session Management: Configurable session timeouts with automatic cleanup
  • • Memory Protection: Sensitive data is cleared from memory after use

Encryption

What encryption does CommandChronicles use?

CommandChronicles uses state-of-the-art cryptography:

Encryption Algorithm

  • • XChaCha20-Poly1305 (authenticated encryption)
  • • 256-bit key size
  • • 192-bit nonce (extended nonce)
  • • Resistance to timing attacks

Key Derivation

  • • Argon2id with configurable parameters
  • • Default: 3 iterations, 64MB memory
  • • 256-bit session keys
  • • Configurable timeout (default: 90 days)

Privacy Controls

Can I exclude sensitive commands?

Currently, CommandChronicles captures all commands executed in shells with installed hooks. However, you can:

  • • Lock Your History: Use ccr lock to require password authentication for searches
  • • Delete Specific Commands: Use ccr delete to remove sensitive commands from history
  • • Disable Temporarily: Uninstall hooks temporarily with ccr uninstall-hooks
  • • Session Control: End sessions cleanly to compartmentalize sensitive work

Future versions may include command filtering and exclusion patterns.

Cross-Device Sync

How does cross-device sync work?

CommandChronicles offers optional cross-device synchronization with perfect integrity:

1
Registration
Register for sync with ccr sync register
2
Perfect Sync
Uses integrity verification to ensure all devices have identical command history
3
Background Daemon
A lightweight daemon runs in the background to automatically sync your commands
4
Device Management
Each device gets a unique ID for tracking and conflict resolution

How much data does sync use?

Sync usage is minimal and efficient:

  • • Command Data: Typically 100-500 bytes per command (depending on length and metadata)
  • • Incremental Sync: Only new/changed commands are synchronized
  • • Compression: Data is compressed during transmission
  • • Estimated Usage: For heavy users (1000 commands/day), expect ~150KB/day of sync data

Offline Usage

Can I use CommandChronicles offline?

Absolutely! CommandChronicles is designed to work offline-first:

  • • Local Storage: All core functionality works without internet connection
  • • Search & TUI: Full search capabilities available offline
  • • Command Recording: Continues capturing commands offline
  • • Sync Queue: Changes are queued and synchronized when connection is restored
  • • Independent Operation: Each device maintains a complete local copy of your history

Daemon Management

How do I control the background daemon?

ccr daemon-control start

Start background sync daemon

ccr daemon-control stop

Stop background sync daemon

ccr daemon-control status

Check daemon status

ccr daemon-control restart

Restart daemon with new settings

ccr daemon-control install-service

Install system service for automatic startup

ccr daemon-control remove-service

Remove system service

Data Storage

Where is my data stored?

CommandChronicles stores data in standard system locations:

  • • Configuration: ~/.config/commandchronicles/config.toml
  • • Database: ~/.local/share/commandchronicles/commands.db
  • • Session Keys: ~/.local/share/commandchronicles/session.key
  • • Shell Hooks: ~/.local/share/commandchronicles/hooks/
  • • Search Index: ~/.local/share/commandchronicles/search_index/ (for fuzzy search)

All files are created with secure permissions (mode 0700/0600) to prevent unauthorized access.

Storage Usage

How much storage space does it use?

Storage usage depends on your command history volume:

Storage Breakdown

  • • Database Overhead: ~50KB for empty database with schema
  • • Per Command: ~200-800 bytes (depending on command length and metadata)
  • • Search Index: ~2-5x the database size (for fuzzy search capabilities)

Example Usage

  • • 10,000 commands ≈ 5-8MB total storage
  • • Heavy user (1000 cmd/day) ≈ 1-2MB/day
  • • Automatic cleanup available

Backup & Export

Can I backup or export my data?

Yes, CommandChronicles provides comprehensive export options:

Export Formats

ccr export --format json

Complete data with metadata

ccr export --format bash

Plain bash history format

ccr export --format csv

Spreadsheet-compatible format

Import Options

ccr import ~/.bash_history --format bash
ccr import ~/.zsh_history --format zsh

Note: Exported data includes timestamps, directories, exit codes, and git information, making it more comprehensive than standard shell history files.

Getting Help

Need additional help?

If you need additional help beyond this FAQ:

CommandChronicles logo

CommandChronicles

The ultimate terminal history tracker for developers.
Never lose a command again. Ever

Product

Resources

Community

© 2025 CommandChronicles. All rights reserved.