Update.
This commit is contained in:
@@ -0,0 +1,339 @@
|
||||
# Tikker CLI Tools - Usage Guide
|
||||
|
||||
This guide demonstrates how to use the four main Tikker command-line tools.
|
||||
|
||||
## Tools Overview
|
||||
|
||||
1. **tikker-decoder** - Convert keystroke tokens to readable text
|
||||
2. **tikker-indexer** - Build word index and analyze frequency
|
||||
3. **tikker-aggregator** - Generate keystroke statistics
|
||||
4. **tikker-report** - Create HTML activity reports
|
||||
|
||||
## Prerequisites
|
||||
|
||||
All tools are compiled C binaries located in `build/bin/`:
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
tikker-decoder <input_file> <output_file>
|
||||
```
|
||||
|
||||
### Examples
|
||||
|
||||
Decode a single day's log:
|
||||
```bash
|
||||
tikker-decoder logs_plain/2024-11-28.txt decoded_2024-11-28.txt
|
||||
```
|
||||
|
||||
Decode with verbose output:
|
||||
```bash
|
||||
tikker-decoder --verbose logs_plain/2024-11-28.txt decoded.txt
|
||||
```
|
||||
|
||||
Show decoding statistics:
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
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:
|
||||
```bash
|
||||
tikker-indexer --index
|
||||
```
|
||||
|
||||
Show top 50 most popular words:
|
||||
```bash
|
||||
tikker-indexer --popular 50
|
||||
```
|
||||
|
||||
Find frequency of specific word:
|
||||
```bash
|
||||
tikker-indexer --find "function"
|
||||
```
|
||||
|
||||
Find with custom database:
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
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:
|
||||
```bash
|
||||
tikker-aggregator --daily
|
||||
```
|
||||
|
||||
Hourly stats for specific day:
|
||||
```bash
|
||||
tikker-aggregator --hourly 2024-11-28
|
||||
```
|
||||
|
||||
Weekly statistics in JSON format:
|
||||
```bash
|
||||
tikker-aggregator --weekly --format json --output weekly.json
|
||||
```
|
||||
|
||||
Weekday comparison:
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
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:
|
||||
```bash
|
||||
tikker-report
|
||||
```
|
||||
|
||||
Custom output file:
|
||||
```bash
|
||||
tikker-report --output activity-report.html
|
||||
```
|
||||
|
||||
With embedded graphs:
|
||||
```bash
|
||||
tikker-report --include-graphs --graph-dir ./graphs --output report.html
|
||||
```
|
||||
|
||||
Custom database and title:
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
for file in logs_plain/*.txt; do
|
||||
tikker-decoder "$file" "decoded/${file%.txt}.txt"
|
||||
done
|
||||
```
|
||||
|
||||
### Generate multiple reports
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
```bash
|
||||
cd src/libtikker && make && cd ../tools && for d in */; do (cd $d && make); done
|
||||
```
|
||||
|
||||
### Permission denied
|
||||
Make tools executable:
|
||||
```bash
|
||||
chmod +x build/bin/tikker-*
|
||||
```
|
||||
|
||||
### Database not found
|
||||
Default locations:
|
||||
- `tags.db` - for word indexer
|
||||
- `tikker.db` - for aggregator and report generator
|
||||
|
||||
Specify custom paths with `--database` option.
|
||||
|
||||
### No data in reports
|
||||
Ensure logs exist in specified directory:
|
||||
```bash
|
||||
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`:
|
||||
```bash
|
||||
tikker-decoder --help
|
||||
tikker-indexer --help
|
||||
tikker-aggregator --help
|
||||
tikker-report --help
|
||||
```
|
||||
|
||||
For detailed information, see the man pages:
|
||||
```bash
|
||||
man tikker-decoder
|
||||
man tikker-indexer
|
||||
man tikker-aggregator
|
||||
man tikker-report
|
||||
```
|
||||
Reference in New Issue
Block a user