Read your saved Bash, Zsh and Fish commands, and — with an opt-in shell hook — record
metadata native history doesn't reliably keep: the working directory, exit code,
start time, duration, user, host, and terminal session. Search commands with keyword
and semantic matching, or rank captured commands for your current directory.
Search uses potion-shell-16m (potion-code-16M-v2 fine-tuned on shell commands), a static model shipped beside the binaries (about 33 MB, MIT licensed,
see Models/). smcli runs on macOS. Linux support coming soon! If the service is unavailable, history search uses keyword matching and @@ ranks existing examples by words; no embedding model is loaded in the CLI.
Note
Native shell history stores the command line and little else. smcli never rewrites that file; it keeps its own private SQLite log alongside.
When a history command names paths, press Ctrl-E in the picker to replace detected paths with @ placeholders and open the files picker on the first one. Enter fills it with a quoted path and leaves the command on the prompt; it never runs the command. Move to another @ and press Tab to pick that path.
$ make release
$ dist/smcli history
==> /Users/you/.zsh_history <==
git status
git push origin main
# ^^ native history, from both shells regardless of the current one
$ dist/smcli search undo last commit
git reset --soft HEAD~1
runs=4 native history
# ^^ illustrative output; native history has no captured time, exit code, or directory
# ^^ the first search embeds distinct commands; later searches index new commands$ dist/smcli suggest
# ^^ no output if you haven't captured or imported any commands
$ eval "$("$PWD/dist/smcli" shell-init zsh)"
$ git status
$ ./run-tests.sh
$ git commit -am 'fix login'
$ dist/smcli suggest
git commit -am 'fix login'
./run-tests.sh
git status
# ^^ illustrative order, assuming successful runs and no earlier captured history
# ^^ ranked for this user and directory: runs here count 4x, ancestor/descendant 2x, failures 0.25xNothing installs itself: shell-init prints the hooks, you eval them. Add the line
to ~/.zshrc (or ~/.bashrc) with the binary's absolute path to keep capturing in new
terminals. Use shell-init bash for Bash. Finished interactive command lines are
saved in SQLite at ~/.local/state/smcli/history.db; recording normally happens in
the background, so the newest command may not appear immediately. Set SMCLI_SYNC=1
in the shell to make recording synchronous.
shell-init binds Up and Ctrl-R to history search. On an empty prompt in Bash and Zsh, Left opens that same search and Right opens directory suggestions, when you chose those keys in smcli init; a line that already has text keeps normal arrow movement. Start typing to filter every captured and native command
(all words must match), press Tab for semantic search, Enter to put the command on your
prompt, Esc to cancel. Text already on the prompt becomes the initial query. Set
SMCLI_NO_KEYS=1 before the eval to keep your shell's own keys, or SMCLI_EXTRA_KEYS=1 to add Left and Right on an empty line, Ctrl-Right and Alt-;. Bash needs 4.0+. Fish keeps Right for autosuggestions. In the shell hooks, press Tab on a word starting with @ to complete a project path; cd offers directories only, and glob characters use glob matching. Nothing changes unless you press Tab.
When @-Tab finds several matches (bash, zsh and fish), the files picker opens inline under the prompt,
showing 12 results:
- A blank
@lists fff's suggestions first, marked ✨: files you open often or recently, files with git changes, and each one's folder. The rest of fff's ranking follows. Once you type, matching files you picked before are marked ✨ and lead. - Tab moves into the selected folder, or into a file's folder; Shift+Tab moves out. The header shows the
folder being searched, e.g.
files+dirs @ ~/project/src/. While editing paths with ^E or @-Tab, it showsedit @ <whole command line>instead. - Both Ctrl-T at the prompt and @-Tab start with folders for
cd,pushd,popd,z,rmdirandmkdir. Other commands use path arguments from their last 20 captured runs: a strict directory or file majority selects that filter; a tie or no evidence shows files+dirs. This works without the service. - ^T cycles files+dirs, folders and files; ^G searches file contents; ^R opens history; Enter inserts the path. Ctrl+Enter (where supported) or Alt+Enter on a directory changes into it without changing the command line; on a file these keys do nothing. Esc leaves the line as it was. Resizing the window re-lays out the picker.
- In the history picker, ^R flips between full history and this directory's suggestions. Only ↑/↓ move the selection.
- Rows use your terminal theme's colours. Config options (in
~/.config/smcli/config.json):"atCompletionLsColors": truecolours rows fromLS_COLORS;"atCompletionInline": falsemakes every picker (history, files, grep) and thesmclimenu fullscreen instead; they all open inline by default. Terminals that never report the cursor position also get the fullscreen picker.
See docs/install.md to install a release or build from source, set up Zsh, Bash or Fish, choose the picker keys, and upgrade or uninstall. In short:
scripts/install.sh # build (needs Rust and a C toolchain), install, hook your shell, start the service
smcli-uninstall # export your history, then remove everythingLinux support coming soon!
smcli history # native history by file, then captured records
smcli history --json # captured records only, as JSON
smcli search [query...] # --limit N, --json, filters below
smcli suggest [prefix...] # --dir PATH, --limit N, --json
smcli shell-init bash|zsh|fish # print opt-in hooks; eval (or `| source` in fish)
smcli pick [query...] # interactive picker; prints the chosen command
smcli init # configure picker keys
smcli init --keys [LIST] # picker keys only: ask, or ctrl-r,left,right | ctrl-r | left | right | none
smcli init --potion [DIR] # use another Model2Vec model dir (no DIR: the built-in one)
smcli init --default # back to the default: the built-in Potion model
smcli reindex # discard the search index and re-embed every command
smcli health [--json] # index coverage, size, and model identity (exit 1 if broken)
smcli import legacy.jsonl # import older smcli JSONL logs (not native history)
smcli import --atuin [db] # import Atuin history (default ~/.local/share/atuin/history.db)
smcli import --atuin --replace [db] # discard existing smcli history, then import
smcli prune [--dry-run] # delete stored commands that current filters rejectRun smcli with no arguments in a terminal for an interactive menu. For the rest:
$ smcli --helpLocal snapshot measured on 2026-11-03 on a MacBookPro18,3 (Apple Silicon, arm64), macOS 27.2, using the installed binaries and an existing personal history. Sizes use MiB (1,048,576 bytes); these are workload-specific measurements, not fixed requirements.
| Component | Size |
|---|---|
CLI binary (smcli) |
13.02 MiB |
Service binary (smcli-service) |
15.90 MiB |
| Shared potion-shell-16m model folder (disk usage) | 31.98 MiB |
The measured installation had two current index/cache files:
| Index/cache | File size | Allocated disk space |
|---|---|---|
| Command-history search index | 68.50 MiB | 49.86 MiB |
| tldr vector cache | 1.41 MiB | 1.41 MiB |
| Total | 69.91 MiB | 51.27 MiB |
The full smcli data directory occupied 70.10 MiB, including these indexes, the SQLite history database and sidecars, and a 6.76 MiB backup. File size and allocated space can differ on the filesystem. Index counts and sizes grow with history, cached examples, and model changes; inspect yours with smcli indexes --json.
| Resource / operation | Observed result |
|---|---|
| CLI peak resident RAM per search/suggest call | About 7.8 MiB |
| Service resident RAM after history searches | About 196 MiB |
| Service idle CPU snapshot | 0.0% |
| Warm history search, 20 sequential runs | 117 ms mean; 112–140 ms range |
| Service CPU time across those 20 searches | 1.51 CPU-seconds (about 65% of one core during the run) |
Search measurements used smcli search 'git status' --limit 5 --json through the running service. CLI peak RAM came from /usr/bin/time -l; service RAM and CPU time came from ps, sampled between calls. The service holds most search state and stays running after the CLI exits. Cold starts, interactive pickers, file/grep workloads, and sustained load were not measured.
- Native history is read from
~/.bash_history,~/.zsh_history, and the.history/.historynewfiles in~/.bash_sessions/~/.zsh_sessions,~/.local/share/fish/fish_history, plus an exportedHISTFILE. It's grouped by file, not merged chronologically — most native files carry no timestamps. - Native history is decoded for display: Bash timestamp lines and Zsh extended-history
prefixes are removed, Zsh escaped bytes are decoded, and Fish
- cmd:records are decoded. The source files aren't changed. - Search combines captured commands and native history, treating each native line as an
entry (not reconstructing multiline commands). It ranks distinct commands by fusing
BM25 keywords (whole words like
--softand their pieces) with potion-shell-16m embeddings. Semantic matches aren't guaranteed. - Literal queries (flags, paths, revisions like
HEAD~1, or a short query led by a program in your history) weight keywords more; plain-language requests fuse both legs by rank. - A bounded pool of matches is reranked with usage aggregates computed in the same SQL
query as the stats: age-weighted runs (a run two weeks old counts half), runs in the
current directory or below, and success rate (Ctrl-C, and exit 1 from
grep/diff-style programs, are not failures). Usage scales with relevance, so habits lift strong matches without surfacing weak ones; failed commands are demoted, not hidden. Text results show why a command ranked (exact words,used here,recent, …). - potion-shell-16m runs natively (WordPiece tokens, mean of float16 rows, normalize;
no network pass). It is shipped in a model folder beside the binaries,
so there is nothing to download;
init --potion DIRpoints at another copy. Being a static model, it embeds only the command and its intent, not the labels below; word order is lost (cp a bequalscp b a), so keywords matter. For commands with captured metadata, run counts come only from captured records; otherwise they count occurrences across native files. Native lines have no times, so their usage decays by position (halving every 1,000 lines from the end); a captured command keeps its native usage when that is the stronger evidence. - Search document identity preserves the full command and intent; embedding input is capped at 1,500 characters and lexical input at 8,192 (
crates/smcli-search/src/corpus.rs:search_document,embedding_text,lexical_text). Keyword input contains executable text, the typed alias when present, and intent, without generated contextual labels. Directories are not embedded: use--dir PATH. Captured commands store option names in aflagscolumn, filled in for existing rows on upgrade. - Hard filters drop non-matching results:
--command git,--subcommand commit,--since 7d,--before 2026-10-01,--min-runs 5,--author NAME,--dir PATH(last run in PATH or below),--flag NAME(exact option name, e.g.--flag --amend). Times are30m/12h/7d/2w,YYYY-MM-DD, or ISO 8601, compared with the command's last run, so time filters exclude native-only history. With filters the query may be empty: matches list by last run. - The index lives next to the database at
history.db.search/and is a rebuildable cache — delete it to reclaim space. Separate model indexes can be reused when switching back to a previously selected model. suggestreads captured/imported history only and filters to the current user; each run is scored by recency (halves every 14 days), directory, and exit status. An optional prefix matches the start of the command literally.--dirrequires an absolute path. Search and suggestions exclude commands recognized as invoking smcli.
Project-index ranking switches are controlled by SMCLI_RANKING_OFF: index, git, evidence, tests and expand each disable a service-only signal; each signal can only raise rank. Add names comma-separated to disable multiple signals.
Warning
History can contain passwords, tokens, and other secrets. smcli does not redact captured commands — don't share the database or the search index. Search embeddings are computed locally with the bundled Potion model.
Note
Capture is best-effort, not an audit. It records finished interactive commands;
commands inside scripts/functions aren't logged individually, and exec, force-killed
shells, and terminal crashes can escape it. Bash hooks refuse installation if DEBUG/EXIT
traps, functrace, or extdebug are already enabled. Older Bash versions time commands
with whole-second precision.
- Keep
SMCLI_DBseparate from your nativeHISTFILE— the CLI rejects the same file, symlink, or hard link. SMCLI_DBoverrides the database path. Search model settings are stored in~/.config/smcli/config.json(or$XDG_CONFIG_HOME/smcli/config.json);SMCLI_CONFIGoverrides that file's path.initconfigures search, not capture, and is not required for the built-in model.importof legacy JSONL is transactional and deduplicates matching imported records; repeated imports preserve existing rows (crates/smcli-core/src/import.rs).- Like Atuin, capture skips commands typed with a leading space, commands containing likely
secrets (AWS, GitHub, GitLab, Slack, Stripe, Google, npm, Anthropic/OpenAI keys), and any
matching regexes in the config file:
"historyFilter": ["^vault "]for commands,"cwdFilter": ["^/Users/me/secret"]for directories. Set"secretsFilter": falseto turn off the secret patterns.pruneapplies the current filters to already-stored history and compacts the database so deleted text is not left on disk. "ignoreFile": "~/.config/smcli/ignore"points file search (Ctrl-T,@-Tab, grep) at a gitignore-syntax file whose matches are left out everywhere; a leading/in a pattern means your home, and a relativeignoreFileis relative to the config's folder. A configured file that is missing or invalid makes file search fail;smcli healthreports it.import --atuinkeeps Atuin's record UUIDs, so re-running it only adds new commands. It also carries over soft deletions (hidden from history, search, and suggestions) and Atuin's optionalauthor/intentfields.ATUIN_DB_PATHorXDG_DATA_HOMEoverride the default source path. Existing smcli databases are upgraded to the new schema on first use.
$ make testRust tests run under cargo-nextest, which runs every crate's tests in
parallel. Install it once with cargo install cargo-nextest --locked. make test is the full
gate: Rust tests plus the black-box CLI, shell, service, picker and install suites. While
editing, run one slice, for example make test-rust PKG=smcli-core FILTER=history. Plain
cargo test still works, but it is slower and runs the ranking tests twice.
Before changing shell transports or search ownership:
make baseline # release CLI; synthetic 1k/10k/100k histories, raw JSON in dist/baseline.json
make test-service # service and file-search black-box checksNormal builds link the pinned fff-search crate into smcli-service only;
smcli does not link fff. Builds require Cargo and a C toolchain. See
the baseline report for the capture-to-picker trace,
measurements, dependency/API verification, limitations, and the next gate.
The executables share smcli-core, the sole owner of captured-history SQL, and smcli-search, the sole owner of index files. smcli-service owns runtime embeddings and alone links fff-search. Without a usable service, history search falls back to keyword matching and @@ to word ranking; service-only fff evidence is unavailable.
- Rust workspace — CLI, shared history/protocol, search library and service boundaries.
- Scripts — install/uninstall, benchmarking, build cleanup and notices.
- The workspace manifest selects
crates/*(Cargo.toml:workspace.members);Makefileexposes build/test/formatting entry points. Source-free docs, model assets and test-only directories are not component contracts.
- Native shell history is read-only; captured history cannot alias
HISTFILE(crates/smcli-search/src/native.rs:HistoryFile::read,crates/smcli-core/src/history.rs:CapturedHistory::check_separate). - History and runtime paths require current-user ownership and private permissions (
crates/smcli-core/src/history.rs:CapturedHistory::connect,service_location.rs:ServiceLocation::prepare). Search caches contain command text and also require a private directory (crates/smcli-search/src/index.rs:prepare_directory). - Protocol JSON is one request/response per connection; version mismatches are rejected in dispatch, while clients handle unavailable/stale services (
crates/smcli-service/src/service.rs:Service::serve,Service::dispatch;crates/smcli-core/src/service_client.rs:ServiceClient). - Embeddings run locally from the shipped model folder, with checkout fallback for development; model-specific index names prevent vector reuse across identities (
crates/smcli-search/src/potion.rs:Potion::bundled,index.rs:HistorySearch::index_name). - Model-changing initialization and reindex stop the service and refuse to load weights if the per-database model lock remains held. The service holds that lock while its model is resident and drops its old engine before loading another (
crates/smcli/src/initialize.rs;crates/smcli-service/src/service.rs:Service::load_engine).
- Persistent captured-history SQLite rows, selection records, migrations and config writes (
crates/smcli-core/src/history.rs:CapturedHistory,config.rs:SmcliConfig::save); rebuildable TalaDB search caches (crates/smcli-search/src/index.rs:HistorySearch). - Service process/socket lifecycle, local filesystem watchers and Git-status subprocesses (
crates/smcli-core/src/service_client.rs:ServiceClient,crates/smcli-core/src/context.rs:GitStatus::read;crates/smcli-service/src/file_search.rs:FileSearch). - Interactive terminal modes and user-opted shell hooks (
crates/smcli/src/picker.rs:TerminalSession,shell_integration.rs:render_config). Install/uninstall can change shell startup files and remove smcli data; see the scripts contract.
Run make test from the repository root. make ranking checks ranking changes; focused gates are listed in child contracts. Run make docs after handwritten Markdown changes; generated THIRD_PARTY_NOTICES.md is excluded by the Makefile.