Tikker CLI Tools - Usage Guide
This guide demonstrates how to use the four main Tikker command-line tools.
Tools Overview
- tikker-decoder - Convert keystroke tokens to readable text
- tikker-indexer - Build word index and analyze frequency
- tikker-aggregator - Generate keystroke statistics
- tikker-report - Create HTML activity reports
Prerequisites
All tools are compiled C binaries located in build/bin/:
build/bin/tikker-decoder
build/bin/tikker-indexer
build/bin/tikker-aggregator
build/bin/tikker-report
tikker-decoder
Converts keystroke token data to readable text.
Basic Usage
tikker-decoder <input_file> <output_file>
Examples
Decode a single day's log:
tikker-decoder logs_plain/2024-11-28.txt decoded_2024-11-28.txt
Decode with verbose output:
tikker-decoder --verbose logs_plain/2024-11-28.txt decoded.txt
Show decoding statistics:
tikker-decoder --stats logs_plain/2024-11-28.txt decoded.txt
Input Format
The input format uses bracket notation for tokens:
[a][b][c] → "abc"
[LEFT_SHIFT][h][e][l][l][o] → "Hello"
[LEFT_SHIFT][a] → "A"
[BACKSPACE] → (removes last character)
[ENTER] → (newline)
[TAB] → (tab character)
[SPACE] → (space)
tikker-indexer
Builds a word index and analyzes word frequency.
Basic Usage
tikker-indexer [options]
Options
--index- Build index from logs_plain directory--popular [N]- Show top N words (default: 10)--find <word>- Find specific word statistics--database <path>- Custom database (default: tags.db)
Examples
Build word index:
tikker-indexer --index
Show top 50 most popular words:
tikker-indexer --popular 50
Find frequency of specific word:
tikker-indexer --find "function"
Find with custom database:
tikker-indexer --database words.db --find "variable"
Output Example
Popular words output:
Top 10 most popular words:
# Word Count Percent
- ---- ----- -------
#1 the 15423 12.34%
#2 function 8921 7.15%
#3 return 7234 5.80%
#4 if 6512 5.22%
#5 for 5623 4.50%
tikker-aggregator
Generates keystroke statistics and summaries.
Basic Usage
tikker-aggregator [options]
Options
--daily- Daily statistics--hourly <date>- Hourly stats for specific date--weekly- Weekly statistics--weekday- Weekday comparison--format <format>- Output format: json, csv, text (default: text)--output <file>- Write to file--database <path>- Custom database (default: tikker.db)
Examples
Daily statistics:
tikker-aggregator --daily
Hourly stats for specific day:
tikker-aggregator --hourly 2024-11-28
Weekly statistics in JSON format:
tikker-aggregator --weekly --format json --output weekly.json
Weekday comparison:
tikker-aggregator --weekday
Output Example
Daily Statistics:
Daily Statistics
================
Total Key Presses: 45623
Total Releases: 45625
Total Repeats: 12341
Total Events: 103589
Weekday Comparison:
Weekday Comparison
==================
Day Total Presses Avg Per Hour
--- -------- ----- --- ---- ----
Monday 12500 521
Tuesday 13200 550
Wednesday 12800 533
Thursday 11900 496
Friday 13100 546
Saturday 8200 342
Sunday 9100 379
tikker-report
Generates comprehensive HTML activity reports.
Basic Usage
tikker-report [options]
Options
--input <dir>- Input logs directory (default: logs_plain)--output <file>- Output HTML file (default: report.html)--graph-dir <dir>- Directory with PNG graphs to embed--include-graphs- Enable graph embedding--database <path>- Custom database (default: tikker.db)--title <title>- Report title
Examples
Generate default report:
tikker-report
Custom output file:
tikker-report --output activity-report.html
With embedded graphs:
tikker-report --include-graphs --graph-dir ./graphs --output report.html
Custom database and title:
tikker-report --database work.db --title "Work Activity Report" --output work-report.html
Output
Generates an HTML file with:
- Dark theme styling
- Activity statistics
- Generation timestamp
- Optional embedded PNG graphs
- Responsive layout
Batch Processing
Decode all logs at once
for file in logs_plain/*.txt; do
tikker-decoder "$file" "decoded/${file%.txt}.txt"
done
Generate multiple reports
for month in 01 02 03; do
tikker-report \
--input "logs_plain/2024-$month" \
--output "reports/2024-$month-report.html" \
--title "Activity Report - November 2024"
done
Database Management
All tools support custom database paths:
# Use separate database for work logs
tikker-indexer --database work-tags.db --index
# Generate report from specific database
tikker-report --database work-logs.db --output work-report.html
# Aggregator with custom database
tikker-aggregator --database stats.db --daily
Performance Notes
- Decoder: ~10x faster than Python version for large files
- Indexer: Builds index for 100K words in < 1 second
- Aggregator: Generates statistics in < 100ms
- Report: Generates HTML in < 500ms with graphs
Troubleshooting
Tools not found
Ensure build is complete:
cd src/libtikker && make && cd ../tools && for d in */; do (cd $d && make); done
Permission denied
Make tools executable:
chmod +x build/bin/tikker-*
Database not found
Default locations:
tags.db- for word indexertikker.db- for aggregator and report generator
Specify custom paths with --database option.
No data in reports
Ensure logs exist in specified directory:
ls logs_plain/
tikker-decoder logs_plain/*.txt # decode first
tikker-indexer --index # build index
tikker-aggregator --daily # generate stats
Backwards Compatibility
These C tools are drop-in replacements for the original Python utilities:
| C Tool | Python Original | Compatibility |
|---|---|---|
| tikker-decoder | ntext.py | 100% |
| tikker-indexer | tags.py | Enhanced (faster) |
| tikker-aggregator | api.py | 100% |
| tikker-report | merge.py | 100% |
All existing scripts and workflows continue to work unchanged.
Getting Help
All tools support --help:
tikker-decoder --help
tikker-indexer --help
tikker-aggregator --help
tikker-report --help
For detailed information, see the man pages:
man tikker-decoder
man tikker-indexer
man tikker-aggregator
man tikker-report