# plk Quickstart
## 1. Build & Install
```sh
cargo build --release
cp target/release/plk ~/.local/bin/ # or anywhere on your $PATH
```
## 2. Set Up the Shell Hook
```sh
plk init --shell zsh # or bash
source ~/.zshrc # reload your shell config
```
This installs a hook that silently records each command you run. If swapx is detected, plk will ask whether to enable integration. Running `plk init` again on an already-initialized setup will offer to enable swapx if it isn't already.
## 3. Use Your Shell Normally
Just keep working. plk records commands in the background. After you've repeated a sequence of commands a few times, plk will detect the pattern.
## 4. See Detected Sequences
```sh
plk ls auto
```
Output looks like:
```
a1b2c3 (3x, 2 steps): cd ~/project/frontend && pnpm run dev
d4e5f6 (2x, 3 steps): cd ~/project && git add . && git commit -m "wip"
```
Each sequence has a 6-char hex ID, a frequency count, and the runnable command.
## 5. Run a Detected Sequence
```sh
plk auto a1b2c3
```
Or just `plk auto` to see all available sequences.
## 6. Save a Sequence as a Shortcut
```sh
plk save a1b2c3 --name dev
```
## 7. Run a Saved Shortcut
```sh
plk run dev
```
## 8. Manage Shortcuts
```sh
# Add one manually
plk add --name deploy "cd ~/project && git push && ./deploy.sh"
# List saved shortcuts
plk ls saved
# Remove a shortcut
plk rm deploy
```
## 9. Suggestions
After you repeat a sequence enough times (default: 10), plk will suggest saving it:
```
plk: "cd ~/project/frontend && pnpm run dev" repeated 10x. Save it? Run: plk save a1b2c3 --name <name>
To dismiss: plk dismiss a1b2c3
```
To stop seeing a suggestion:
```sh
plk dismiss a1b2c3
```
## 10. Maintenance
```sh
# Clean up old history entries (older than 30 days)
plk gc
# Wipe all history, shortcuts, and config
plk reset
```
## File Locations
| History log | `~/.local/share/plk/history.log` |
| Saved shortcuts | `~/.local/share/plk/shortcuts.json` |
| Dismissed suggestions | `~/.local/share/plk/dismissed.json` |
| Config (optional) | `~/.config/plk/config.toml` |
Override with `PLK_DATA_DIR` and `PLK_CONFIG_DIR` environment variables.
## 11. swapx Integration (Optional)
If you use [swapx](https://github.com/beepboopbit/swapx), plk can automatically create swapx rules for your shortcuts. During `plk init`, if swapx is detected, you'll be asked:
```
swapx detected. Enable swapx integration? (y/N)
```
Or enable it manually:
```toml
# ~/.config/plk/config.toml
swapx_integration = true
```
When you save a shortcut, plk asks whether the rule should be global or directory-scoped:
```
Swapx rule scope — directory (/home/user/projects) or global? (d/G)
```
Rules are written to `~/.config/swapx/rules.plk.yaml` — your manual swapx rules in `rules.yaml` are never modified.
Now when you type the first command of a shortcut (e.g., `cd prompt`), swapx intercepts it and offers to run the full sequence via `plk run dev`. Removing shortcuts or resetting plk cleans up `rules.plk.yaml` automatically.
## Optional Config
Create `~/.config/plk/config.toml`:
```toml
# Time gap (ms) that splits command history into separate sessions (default: 5000)
session_gap_ms = 5000
# Minimum times a sequence must repeat to be detected (default: 2)
min_frequency = 2
# Only consider history from the last N days (default: 30)
history_days = 30
# Maximum history entries to keep (default: 10000)
max_history_entries = 10000
# Suggest saving a sequence after this many repetitions (default: 10, 0 to disable)
suggestion_threshold = 10
# Enable swapx integration (default: false)
swapx_integration = false
```