sk(1)

📦
version 5.9.0 · 5 versions
, in arch rolling

💅 sk(1) — Fuzzy Finder in rust! 🦋

okay so like, welcome to the sk page, bestie — it's from the General Commands Manual and honestly it's giving main character energy from the very first line. ✨ We're gonna walk through the whole thing together, no cap, every single flag included. Buckle up. 🎀

🌸 NAME 🌸

sk — Fuzzy Finder in rust! 🦀✨

🌈 SYNOPSIS 🌈

okay so this is the big vibe-check wall of options. Don't panic, it's literally just every flag the thing accepts, laid out exactly like this:

sk [--tac] [--min-query-length] [--no-sort] [-t|--tiebreak] [-n|--nth]
[--with-nth] [--hide-nth] [-d|--delimiter] [-e|--exact] [--regex]
[--algo] [--case] [--typos] [--no-typos] [--normalize] [--split-match]
[--last-match] [--scheme] [-b|--bind] [-m|--multi] [--no-multi]
[--no-mouse] [-c|--cmd] [-i|--interactive] [-I ] [--color]
[--highlight-line] [--no-hscroll] [--keep-right] [--skip-to-pattern]
[--no-clear-if-empty] [--no-clear-start] [--no-clear] [--show-cmd-error]
[--cycle] [--disabled] [--disable-pattern] [--layout] [--reverse]
[--height] [--no-height] [--min-height] [--margin] [-p|--prompt]
[--cmd-prompt] [--selector] [--multi-selector] [--ansi] [--tabstop]
[--info] [--no-info] [--inline-info] [--header] [--header-lines]
[--separator] [--no-separator] [--border] [--border-no-collapse]
[--no-border] [--wrap] [--multiline] [--scrollbar] [--no-scrollbar]
[--history] [--history-size] [--cmd-history] [--cmd-history-size]
[--preview] [--preview-window] [--image] [-q|--query] [--cmd-query]
[--read0] [--print0] [--print-query] [--print-cmd] [--print-score]
[--print-header] [--print-current] [--output-format] [--no-strip-ansi]
[-1|--select-1] [-0|--exit-0] [--sync] [--pre-select-n]
[--pre-select-pat] [--pre-select-items] [--pre-select-file]
[-f|--filter] [--shell] [--shell-bindings] [--man] [--listen] [--remote]
[--popup] [--popup-name] [--log-level] [--log-file] [--expect]
[-h|--help] [-V|--version]

(yes, [-I ] really does have a space in it, that's not a typo, that's just how it is 💀)

✨ OPTIONS ✨

these are the base-level, everyone-gets-them options. short and sweet, like a good coffee order. ☕

  • -h, --help — prints the help text. and heads up: it goes "see a summary with -h", so if you want the short version you already know where to look 👀
  • -V, --version — prints the version. that's it. that's the whole job. iconic behavior. 👑

the part where sk actually finds stuff. this is the whole reason we're here, bestie. let's get into it. 💅

  • --tac — shows results in reverse order. 🔁

ngl this one is often used in combination with --no-sort. they're like a package deal.

  • --min-query-length <MIN_QUERY_LENGTH> — the minimum query length before it starts showing results. ⏳

so like, it only shows results when your query is at least this many characters long. and in interactive mode with --cmd, it also waits before running the command. under --disabled it has no effect at all — literally does nothing there, so don't bother. 🙈

  • --no-sort — does not sort the results. chaotic, but valid. 🌀

often used in combination with --tac. example time, keep this exactly:

history | sk --tac --no-sort
  • -t, --tiebreak <TIEBREAK> [default: score,begin,end] — a comma-separated list of sort criteria to apply when the scores are tied. 🤝

think of it as the tiebreaker round in a beauty pageant. here's the criteria:

  • score: the score from the fuzzy match algorithm.
    • each criterion could be negated, e.g. (-index)
    • each criterion should appear only once in the list — no duplicates, that's not the vibe 🚫

possible values:

  • score
  • -score
  • begin
  • -begin
  • end
  • -end
  • length
  • -length
  • index
  • -index
  • pathname
  • -pathname
  • -n, --nth <NTH> [default: ] — which fields get matched. 🎯

a field index expression can be a non-zero integer or a range expression ([BEGIN]..[END]). and --nth and --with-nth both take a comma-separated list of field index expressions. slay, very flexible.

examples:

1      The 1st field
2      The 2nd field
-1     The last field
-2     The 2nd to last field
3..5   From the 3rd field to the 5th field
2..    From the 2nd field to the last field
..-3   From the 1st field to the 3rd to the last field
..     All the fields
  • --with-nth <WITH_NTH> [default: ] — fields to be transformed. 🪄

see nth for the details, it's the same energy, just for transforming.

  • --hide-nth <HIDE_NTH> [default: ] — fields to hide from the display while keeping them searchable. 🫣

it takes the same comma-separated field index expressions as nth. the listed fields get removed from the displayed line but they remain part of the text used for matching — so a query can still match them. characters in the hidden fields are ignored for match highlighting and horizontal scrolling. sneaky AND useful, we love that.

see nth for the field index expression syntax.

  • -d, --delimiter <DELIMITER> [default: [\t\n ]+] — the delimiter between fields. ✂️

it's in regex format, and it defaults to AWK-style. escape sequences like \x00, \t, \n are supported. fancy. 💅

  • -e, --exact — runs in exact mode. no fuzzy, no vibes, just exact. 🎯
  • --regex — starts in regex mode instead of fuzzy-match. for the regex girlies. 🌸
  • --algo <ALGORITHM> [default: arinae] — which fuzzy matching algorithm to use. 🧠
    • arinae (ari): latest algorithm
    • skim_v2: legacy skim algorithm
    • clangd: used in clangd for keyword completion
    • fzy: algorithm from fzy (<https://github.com/jhawthorn/fzy>)
    • frizbee: algorithm used in the blink.cmp neovim plugin

possible values:

  • arinae: Arinae: typo-resistant & natural algorithm, default
  • clangd: Clangd fuzzy matching algorithm
  • fzy: Fzy matching algorithm (https://github.com/jhawthorn/fzy)
  • frizbee: Frizbee matching algorithm, typo resistant
  • skim_v2: Previous skim fuzzy matching algorithm (v2)
  • --case <CASE> [default: smart] — case sensitivity. 🔠

determines whether or not to ignore case while matching. note: this is not used for the Frizbee matcher, which uses a penalty system to favor case-sensitivity without enforcing it. so like, frizbee plays by its own rules, respect it.

possible values:

  • respect: case-sensitive matching
  • ignore: case-insensitive matching
  • smart: smart case: case-insensitive unless query contains uppercase
  • --typos [<TYPOS>] [default: disabled] — enables typo-tolerant matching. 🫶

when passed without a value (--typos), it uses the adaptive formula (pattern_length / 4). when passed with a value (e.g. --typos=2), it uses that exact number as the maximum allowed typos. and --typos=0 explicitly disables typo tolerance. applies to both the fzy and frizbee matchers. we love a forgiving queen. 😌

  • --no-typos — disables typo-tolerant matching. back to strict mode, bestie. 🚫
  • --normalize — normalizes unicode characters. 🌍

when set, it normalizes accents and other unicode diacritics/others. so é and e can finally be friends.

  • --split-match [<SPLIT_MATCH>...] — enables split matching and sets the delimiter. ✂️

split matching runs the matcher in splits: foo:bar will match all items matching foo, then :, then bar if the delimiter is present — or match normally if it's not. lowkey genius.

  • --last-match — highlights the last match found, not the first one. 🔚

this makes tiebreak more pertinent on path items where we want to prioritize a match on the last parts. path girlies, this one's for you. 🛤️

  • --scheme <SCHEME> [default: default] — the search scheme. 🎨

possible values:

  • default: default scheme, no modifications to the options
  • path: path scheme: will find the furthest match in the item and set pathname as the main tiebreak
  • history: history scheme: will force index as the first tiebreak

🎀 a few more things about --bind 🎀

Multiple actions can be chained using + separator.

Example: sk --bind 'ctrl-a:select-all+accept'

Special behaviors ✨

With the execute(...) and reload(...) actions, you can execute arbitrary commands without leaving sk. For example, you can turn sk into a simple file browser by binding the enter key to the less command like this:

sk --bind "enter:execute(less {})"

Note: if no argument is supplied to reload, the default command is run.

You can use the same placeholder expressions as in --preview.

sk switches to the alternate screen when executing a command. However, if the command is expected to complete quickly, and you aren't interested in its output, you might want to use execute-silent instead — it silently executes the command without the switching. Note that sk will not be responsive until the command is complete. For asynchronous execution, start your command as a background process (i.e. appending &). 👀

With the if-query-empty and if-query-not-empty actions, you can specify which action to execute depending on the query condition. For example:

sk --bind 'ctrl-d:if-query-empty(abort)+delete-char'

If the query is empty, skim will execute abort, otherwise it executes delete-char. It's equal to 'delete-char/eof'. slay 💅

  • -m, --multi — turn on multiple selection, bestie. Uses Tab and S-Tab for selection by default.
  • --no-multi — nope, no multiple selection, we're doing one thing at a time 🫶
  • --no-mouse — mouse? off. gone. not invited to the party 🙈
  • -c, --cmd <CMD> — the command to invoke dynamically in interactive mode. It gets invoked using sh -c on Unix-like systems and cmd /c on Windows.
  • -i, --interactive — start skim in interactive mode. In interactive mode, sk will run the command specified by the --cmd option and display the results. 🔥
  • -I <REPLSTR> — replace replstr with the selected item in commands. [default: {}]
  • --color <COLOR> — set the color theme, aesthetic queen 🎀 Format: [BASE][,COLOR:ANSI[:ATTR1:ATTR2:..]] — see the [THEME] section for details. Repeated --color options are merged in order, so a later value overrides an earlier one for the same element.
  • --highlight-line — highlight the entire current line, not just the text. the whole vibe, not just the words ✨
  • --no-hscroll — disable horizontal scroll
  • --keep-right — keep the right end of the line visible on overflow. Effective only when the query string is empty.
  • --skip-to-pattern <SKIP_TO_PATTERN> — show the matched pattern at the line start. The line will start with the start of the matched pattern. Effective only when the query string is empty. Was designed to skip showing starts of paths of rg/grep results. e.g. sk -i -c "rg {q} --color=always" --skip-to-pattern '[^/]*:' --ansi
  • --no-clear-if-empty — don't clear the previous line if the command returns an empty result. Don't clear previous items if a new command returns an empty result. This might be useful to reduce flickering when you're typing new commands and the half-complete commands aren't valid. It's not the default behavior because similar use cases for grep and rg have already been optimized, where empty query results actually mean "empty" and previous results should be cleared.
  • --no-clear-start — don't clear items on start
  • --no-clear — don't clear the screen on exit. Don't clear the finder interface on exit either. If skim was started in full screen mode, it will not switch back to the original screen, so you'll have to manually run tput rmcup to return. This option can be used to avoid flickering of the screen when your application needs to start skim multiple times in order. 😭 careful with this one
  • --show-cmd-error — show an error message if the command fails 💀
  • --cycle — cycle the results by wrapping around when scrolling 🔁
  • --disabled — disable matching entirely
  • --disable-pattern <DISABLE_PATTERN> — disable items based on this regex pattern

🦋 LAYOUT 🦋

  • --layout <LAYOUT> — set the layout. [default: default] Possible values:
    • default: display from the bottom of the screen
    • reverse: display from the top of the screen
    • reverse-list: display from the top of the screen, prompt at the bottom
  • --reverse — shorthand for reverse layout, iykyk
  • --height <HEIGHT> — height of skim's window. [default: 100%] Can either be a row count or a percentage. A negative row count will use term height - value as the height.
  • --no-height — disable height (force full screen), main character energy 👑
  • --min-height <MIN_HEIGHT> — minimum height of skim's window as a non-negative row count. [default: 10] Must be a non-negative row count, not a percentage. Useful when the height is set as a percentage. Ignored when --height is not specified.
  • --margin <MARGIN> — screen margin. [default: 0] For each side, it can be either a row count or a percentage of the terminal size. Format can be one of:
    • TRBL
    • TB,RL
    • T,RL,B
    • T,R,B,L

Example: 1,10%

  • -p, --prompt <PROMPT> — set the prompt. [default: > ] 💖
  • --cmd-prompt <CMD_PROMPT> — set the prompt in command mode. [default: c> ]
  • --selector <SELECTOR_ICON> — set the selected item icon. [default: >]
  • --multi-selector <MULTI_SELECT_ICON> — set the multi-selected item icon. [default: >] 🫶

✨ DISPLAY ✨

  • --ansi — bestie, this one parses the ANSI color codes straight out of your input strings 🌈

Ok but heads up — when you're using skim as a library, this flag does literally nothing 😭 you gotta enable ansi parsing manually by injecting a cmd_collector like this:

use skim::prelude::*;

let _options = SkimOptionsBuilder::default()
  .cmd("ls --color")
  .cmd_collector(Rc::new(RefCell::new(SkimItemReader::new(
    SkimItemReaderOption::default().ansi(true),
    ))) as Rc<RefCell<dyn CommandCollector>>)
  .build()
  .unwrap();
  • --tabstop <TABSTOP> [default: 8] — how many spaces make up one tab 🫶
  • --info <INFO> [default: default] — where the matching-result count shows up 💅
    • hidden — do not display info at all, gone, invisible
    • inline[:SEP] — display info in the same row as the input, with an optional non-default separator
    • default — display info in a dedicated row above the input
    • left — display all info left-aligned in a dedicated row above the input
    • right — display all info right-aligned in a dedicated row above the input
    • inline-right[:SEP] — display info right-aligned in the same row as the input, with an optional non-default separator
  • --no-info — alias for --info=hidden 🙈
  • --inline-info — alias for --info=inline ✨
  • --header <HEADER> — set the header, displayed next to the info 👑

The string you give gets printed as the sticky header. The lines show up in the order you gave them, top to bottom, no matter what the --layout option says, and they're not affected by --with-nth. Also, ANSI color codes get processed here even when --ansi is not set — periodt.

  • --header-lines <HEADER_LINES> [default: 0] — how many lines of the input get treated as header 🎀

The first N lines of your input become the sticky header. And when --with-nth is set, those lines get transformed exactly like all the other lines that follow.

  • --separator <SEPARATOR> — draw a repeating horizontal separator on the status line 🦋

With inline info, it follows the status on the prompt line. With inline-right or hidden info, it occupies a separate line. Disabled by default, and an empty string also disables it. An enabled border row gets reused where possible.

  • --no-separator — disable the horizontal separator, bye 👋
  • --border [<BORDER>...] [default: none] — draw borders around the UI components, it's giving framed 🖼️

Possible values:

  • force-off: ForceOff disables borders around popups too, set with no_border
  • none
  • plain
  • rounded
  • double
  • thick
  • light-double-dashed
  • heavy-double-dashed
  • light-triple-dashed
  • heavy-triple-dashed
  • light-quadruple-dashed
  • heavy-quadruple-dashed
  • quadrant-inside
  • quadrant-outside
  • --border-no-collapse — do not collapse adjacent borders into a shared row or column 🚫
  • --no-border — disables all borders, including in tmux/zellij popups 💀
  • --wrap — wrap items in the item list 🎁
  • --multiline [<MULTILINE>] — split item text into multiple display lines at the given separator character; defaults to \n if read0 is set, and \\n if not (matching literal \n in text) 🧚

Each item's text gets split on the separator, and each part is displayed as its own separate line within that item's row. It's giving multi-line main character energy.

  • --scrollbar <THUMB> [default: ▐] — set the scrollbar style for the item list 🌸

The optional value is what's used as the indicator.

  • --no-scrollbar — disable the scrollbar in the item list, minimalism slay ✨
  • --popup [<POPUP>...] — run in a tmux or zellij popup, pop off queen 👑

Format: sk --popup <center|top|bottom|left|right>[,SIZE[%]][,SIZE[%]]

Note: this will try to detect a Zellij session, then a Tmux session. Which means that in nested sessions, skim prioritizes Zellij over Tmux.

The popup pane is named after --popup-name (default: skim).

  • --popup-name <POPUP_NAME> — name of the popup pane (Zellij) / title of the popup (tmux) 🏷️

Only used with --popup. Defaults to skim in Zellij; tmux popups get no title unless this is set. Oh and --border-label is accepted as an fzf-compatible alias, iykyk.

🕰️ HISTORY 🕰️

  • --history <HISTORY_FILE> — history file, bestie 📖

Loads search history from the specified file and updates that file on completion.

When enabled, CTRL+N and CTRL+P are automatically remapped to next-history and previous-history.

  • --history-size <HISTORY_SIZE> [default: 1000] — maximum number of query history entries to keep 🍓
  • --cmd-history <CMD_HISTORY_FILE> — command history file 📜

Loads command query history from the specified file and updates that file on completion.

When enabled, CTRL+N and CTRL+P are automatically remapped to next-history and previous-history (yes, same deal as above, it's that iconic).

  • --cmd-history-size <CMD_HISTORY_SIZE> [default: 1000] — maximum number of query history entries to keep 💜

👀 PREVIEW 👀

  • --preview <PREVIEW> — preview command, the moment you've all been waiting for 🎬

Executes the given command with sh -c on linux and cmd /c on windows for the current line, and displays the result on the preview window. {} in the command is the placeholder that gets replaced with the single-quoted string of the current line. To transform the replacement string, specify field index expressions between the braces (see FIELD INDEX EXPRESSION for the deets).

Examples:

sk --preview='head -$LINES {}'
ls -l | sk --preview="echo user={3} when={-4..-2}; cat {-1}" --header-lines=1
  • --preview-window <PREVIEW_WINDOW> [default: right:50%] — preview window layout 🪟

Format: [up|down|left|right][:SIZE][:hidden][:[no]wrap][:[no]pty][:+SCROLL[-OFFSET]]

Determines the layout of the preview window. If the argument ends with :hidden, the preview window will be hidden by default until the toggle-preview action is triggered. Long lines are truncated by default. Line wrap can be enabled with the :wrap flag. For more interactive commands, or previews that draw complex interfaces, the preview can use a PTY with the :pty flag.

Note: the preview will run in a PTY (interactive session) on Linux and when wrap is unset.

SIZE can be either:

  • 0, which will hide the preview window
  • A positive size (eg 20)
  • A percentage of the total size (eg 50%)
  • A negative size, which will set the size of everything but the preview to that value

+SCROLL[-OFFSET] determines the initial scroll offset of the preview window. SCROLL can be either a numeric integer or a single-field index expression that refers to a numeric integer. The optional -OFFSET part is for adjusting the base offset so you can see the text above it. It should be given as a numeric integer (-INTEGER), or as a denominator form (-/INTEGER) for specifying a fraction of the preview window height.

Examples:

# Non-default scroll window positions and sizes
sk --preview="head {}" --preview-window=up:30%
sk --preview="file {}" --preview-window=down:2

# Initial scroll offset is set to the line number of each line of
# git grep output *minus* 5 lines (-5)
git grep --line-number '' |
  sk --delimiter:  --preview 'nl {1}' --preview-window +{2}-5

# Preview with bat, matching line in the middle of the window (-/2)
git grep --line-number '' |
  sk --delimiter : \
      --preview 'bat --style=numbers --color=always --highlight-line {2} {1}' \
      --preview-window +{2}-/2
  • --image [<IMAGE>...] — enable image preview, we're visual now 🖼️✨

This renders the preview argument as an image instead of running it as a command.

If set to detect, or if no value is passed, it will try to detect the available image backends at startup — which adds a small delay before the first render. If set to halfblocks, it will always use the halfblocks rendering method.

Note: the backend detection will not work when piping data into skim. Use SKIM_DEFAULT_COMMAND="find . -type f" sk --image instead of find . -type f | sk --image — no cap, that's the move.

Possible values:

  • detect: Default — automatically detect the available backend at startup
  • halfblocks: Force halfblocks if you want blurry previews but a faster startup, or if the detection fails

💅 SCRIPTING ✨

okay so this is the stash of flags you reach for when you're scripting sk instead of just vibing in the TUI 🫶

  • -q, --query <QUERY> — the initial query, bestie. the thing that's already typed in when sk opens 👑
  • --cmd-query <CMD_QUERY> — the initial query, but for interactive mode specifically 💫
  • --read0 — read the input delimited by ASCII NUL(\0) characters 🫧
  • --print0 — print the output delimited by ASCII NUL(\0) characters 💀
  • --print-query — print the query as the first line 📝
  • --print-cmd — print the command as the first line (after print-query) 🎀
  • --print-score — print the score after each item 🔥
  • --print-header — print the header as the first line (after print-score) 🌸
  • --print-current — print the current (highlighted) item as the first line (after print-header) ⭐
  • --output-format <OUTPUT_FORMAT> — set the output format. If set, it overrides all print_ options. It gets expanded the same way as preview or commands ✨
  • --no-strip-ansi — print the ANSI codes, making the output exactly match the input even when --ansi is on 🌈
  • -1, --select-1 — do NOT enter the TUI if the query passed in -q matches only one item, just return it 🎯
  • -0, --exit-0 — do NOT enter the TUI if the query passed in -q doesn't match any item 🙈
  • --sync — synchronous search for multi-staged filtering. If you specify it, skim will launch the TUI finder only after the input stream is complete. e.g. sk --multi | sk --sync 🦋
  • --pre-select-n <PRE_SELECT_N> [default: 0] — pre-select the first n items in multi-selection mode 💜
  • --pre-select-pat <PRE_SELECT_PAT> [default: ] — pre-select the matched items in multi-selection mode. check the doc for the detailed syntax: https://docs.rs/regex/1.4.1/regex/ 🧚
  • --pre-select-items <PRE_SELECT_ITEMS> [default: ] — pre-select the items separated by newline character. Example: 'item1\nitem2' 🍓
  • --pre-select-file <PRE_SELECT_FILE> — pre-select the items read from this file 🎀
  • -f, --filter <FILTER> — the query for filter mode 🔍
  • --shell <SHELL> — generate a shell completion script. Generates the completion script for the specified shell: bash, zsh, fish, etc. The output can be directly sourced or saved to a file for automatic loading. Examples: source <(sk --shell bash) (immediate use), sk --shell bash >> ~/.bash_completion (persistent use). Supported shells: bash, zsh, fish, powershell, elvish. Possible values are:
    • bash — Bourne Again SHell
    • elvish — Elvish shell
    • fish — Friendly Interactive SHell
    • nushell — Nushell (nu)
    • power-shell — PowerShell
    • zsh — Zsh
  • --shell-bindings — generate shell key bindings — only for bash, zsh and fish. Generates the key bindings script after the shell completions. see the --shell option for more details 💫
  • --man — generate the man page and output it to stdout 📖 (yes, sk can print its own man page, main character energy fr)
  • --listen [<LISTEN>...] — run an IPC socket with an optional name (defaults to sk). The socket expects Actions in Ron format (similar to Rust code), see ./src/tui/event.rs for all possible Actions. To write to it, see the --remote option or the man page 🛰️
  • --remote [<REMOTE>...] — send commands to an IPC socket with an optional name (defaults to sk). The commands are read from stdin, one per line, in the same format as the actions in the bind flag. They can also be chained using + as a separator. All other arguments will be ignored 📡
  • --log-level <LOG_LEVEL> — set the log level 🎚️
  • --log-file <LOG_FILE> — pipe log output to a file 🗂️

🌈 DEPRECATED 🫠

  • --expect <EXPECT> [default: ] — deprecated, kept for compatibility purposes. See accept() bind instead ✨
lowkey do not use this one for new stuff, it's literally just vibing here so old configs don't break 💀

👑 MODES 💅

Normal mode

In normal mode, sk reads the input from stdin and displays the results interactively, and the query is then used to fuzzily filter among the input lines. classic. iconic. the standard 🎀

Interactive mode

Interactive mode is a special mode that lets you run a command interactively and display the results. It's enabled by the --interactive (or -i) option, or by binding the toggle-interactive action (default: Ctrl+q). The command is specified with the --cmd option 🦋

Example: sk --cmd 'rg {} --color=always' --interactive will use rg to search for the query in the current directory and display the results interactively ✨

🔍 SEARCH 🌸

By default, skim will start in extended search, giving some characters meaning. Example: ^test rs$ | sh$ will match items starting with test and ending with rs or sh 💖

AND (space)

A space between terms acts as an 'and' operator and filters for items matching all the terms 🤝

OR (|)

A vertical bar between terms acts as an 'or' operator and filters for items matching one of the terms 🌈

Exact match (')

If a term is prefixed by a ', sk will search for exact occurrences of that term. Exact search can be enabled by default with the --exact command-line flag. In exact mode, ' will disable exact matching for that term 🎯

Anchored match (^|$)

If a term is prefixed by a ^ (resp. suffixed by a $), sk will search for matches starting (resp. ending) with that exact term ⚓

Negation (!)

If a term is prefixed by !, sk will exclude the items that match this term 🚫

✨ KEYBINDS ✨

okay bestie, this is where skim becomes yours. You set bindings with the --bind option, which takes a comma-separated list of <trigger>:<action>[+action2] expressions. A trigger can be a key, a finder event, or an action name. Actions can take arguments, and you can write those either between parentheses like reload(ls) or after a colon like reload:ls. Both are valid, no cap. 💅

🔑 Available keys (aliases in parentheses)

here’s the whole key roster, literally every one:

  • ctrl-[a-z]
  • ctrl-space
  • ctrl-alt-[a-z]
  • alt-[a-zA-Z]
  • alt-[0-9]
  • f[1-12]
  • enter
  • space
  • bspace (bs)
  • alt-up
  • alt-down
  • alt-left
  • alt-right
  • alt-enter
  • alt-space
  • alt-bspace (alt-bs)
  • alt-/
  • tab
  • btab (shift-tab)
  • esc
  • del
  • up
  • down
  • left
  • right
  • home
  • end
  • pgup
  • pgdn
  • shift-up
  • shift-down
  • shift-left
  • shift-right
  • alt-shift-up
  • alt-shift-down
  • alt-shift-left
  • alt-shift-right
  • double-click
  • any single character

🛎️ Bindable finder events

these are the finder moments skim can react to, and yes they all slap:

  • change: the query changes
  • start: skim enters its event loop; fired once
  • load: the reader and matcher finish consuming the current input; fired once per read, including reloads
  • result: filtering for the current query completes
  • focus: the focused item changes because of cursor movement or a result update
  • zero: the input stream is complete and the final search has no matches
  • one: the input stream is complete and the final search has exactly one match

🎬 Actions as binding triggers

Actions can also be used as binding triggers. A follow-up chain bound to an action name runs immediately after that action. Use the act- prefix for action triggers; it is recommended to avoid ambiguity and required when the action name is also a key, for example act-up:last.

Follow-up chains use non-recursive (noremap) semantics: their actions do not trigger further action bindings. Add suppress to skip the triggering action's default behavior, for example act-up:suppress+down. that little detail is lowkey important, so don’t skip it. 🫶

💫 Actions

here’s the action buffet — every single one, no skips:

  • abort — Abort and exit with error
  • accept(...) — Accept selection and exit with optional key. The argument is printed when the binding is triggered.
  • add-char(...) — Add a character to the query
  • append-and-select — Append to selection and select
  • backward-char — Move cursor backward one character
  • backward-delete-char — Delete character before cursor
  • backward-delete-char/eof — Delete character before cursor or exit if the query is empty
  • backward-kill-word — Delete word before cursor
  • backward-word — Move cursor backward one word
  • beginning-of-line — Move cursor to beginning of line
  • bind(...) — Bind one or more keys to action chains. The argument is a comma-separated list of trigger:action[+action] bindings to add, using the same syntax as --bind, including action triggers such as act-up:last.
  • cancel — Cancel current operation
  • clear-screen — Clear the screen
  • delete-char — Delete character under cursor
  • delete-char/eof — Delete character or exit if empty
  • deselect-all — Deselect all items
  • down(...) — Move selection down by N items
  • end-of-line — Move cursor to end of line
  • execute(...) — Execute a command. The argument is a command, see COMMAND EXPANSION for details.
  • execute-silent(...) — Execute a command silently. The argument is a command, see COMMAND EXPANSION for details.
  • first — Jump to first item in list
  • forward-char — Move cursor forward one character
  • forward-word — Move cursor forward one word
  • if-query-empty(...) — Execute action if query is empty
  • if-query-not-empty(...) — Execute action if query is not empty
  • if-non-matched(...) — Execute action if no items match
  • ignore — Ignore the action
  • kill-line — Delete from cursor to end of line
  • kill-word — Delete word after cursor
  • last — Jump to last item in list
  • next-history — Move to next history entry (requires --history or --cmd-history)
  • half-page-down(...) — Scroll down by half a page
  • half-page-up(...) — Scroll up by half a page
  • page-down(...) — Scroll down by a page
  • page-up(...) — Scroll up by a page
  • preview-up(...) — Scroll preview up
  • preview-down(...) — Scroll preview down
  • preview-left(...) — Scroll preview left
  • preview-right(...) — Scroll preview right
  • preview-page-up(...) — Scroll preview up by a page
  • preview-page-down(...) — Scroll preview down by a page
  • previous-history — Move to previous history entry (requires --history or --cmd-history)
  • redraw — Redraw the screen
  • refresh-cmd — Refresh the command
  • refresh-preview — Refresh the preview
  • restart-matcher — Restart the matcher
  • reload(...) — Reload with optional new command
  • rotate-mode — Rotate through matching modes
  • scroll-left(...) — Scroll item list left
  • scroll-right(...) — Scroll item list right
  • select-all — Select all items
  • select-row(...) — Select a specific row
  • select — Select current item
  • suppress — Suppress the default behaviour of the action this is bound to. Only meaningful as a follow-up bound to an action (e.g. act-up:suppress): it cancels that action's own effect, so the remaining follow-up chain runs in its place. On its own it is a no-op (equivalent to ignore).
  • set-cmd(...) — Set the interactive-mode command and rerun it. The argument is an expanded expression, see COMMAND EXPANSION for details.
  • set-header(...) — Set the header (or disable it on an empty value)
  • set-preview-cmd(...) — Set the preview cmd and rerun preview. The argument is an expanded expression, see COMMAND EXPANSION for details.
  • set-query(...) — Set the query to the expanded value. The argument is an expanded expression, see COMMAND EXPANSION for details.
  • toggle — Toggle selection of current item
  • toggle-all — Toggle selection of all items
  • toggle-in — Toggle and move in
  • toggle-interactive — Toggle interactive mode
  • toggle-out — Toggle and move out
  • toggle-preview — Toggle preview visibility
  • toggle-preview-wrap — Toggle preview line wrapping
  • toggle-sort — Toggle sorting
  • top — Jump to first item in list (alias for First)
  • unbind(...) — Unbind one or more keys. The argument is a comma-separated list of keys or action triggers (e.g. act-up) to unbind.
  • unix-line-discard — Discard line (unix-style)
  • unix-word-rubout — Delete word backward (unix-style)
  • up(...) — Move selection up by N items
  • yank — Yank (paste)

🎀 Default key bindings

out of the box, these are already wired up bestie:

  • alt-b — backward-word
  • alt-bspace — backward-kill-word
  • alt-d — kill-word
  • alt-f — forward-word
  • alt-h — scroll-left
  • alt-l — scroll-right
  • bspace — backward-delete-char
  • btab — toggle+up
  • ctrl-a — beginning-of-line
  • ctrl-b — backward-char
  • ctrl-c — abort
  • ctrl-d — abort
  • ctrl-e — end-of-line
  • ctrl-f — forward-char
  • ctrl-g — abort
  • ctrl-h — backward-delete-char
  • ctrl-j — down
  • ctrl-k — up
  • ctrl-l — clear-screen
  • ctrl-left — backward-word
  • ctrl-n — down
  • ctrl-p — up
  • ctrl-q — toggle-interactive
  • ctrl-r — rotate-mode
  • ctrl-right — forward-word
  • ctrl-u — unix-line-discard
  • ctrl-w — unix-word-rubout
  • ctrl-y — yank
  • del — delete-char
  • double-click — accept
  • down — down
  • end — end-of-line
  • enter — accept
  • esc — abort
  • home — beginning-of-line
  • left — backward-char
  • pgdn — page-down
  • pgup — page-up
  • right — forward-char
  • shift-btab — toggle+up
  • shift-down — preview-down
  • shift-home — beginning-of-line
  • shift-left — backward-word
  • shift-right — forward-word
  • shift-tab — toggle+up
  • shift-up — preview-up
  • tab — toggle+down
  • up — up

🌈 COMMAND EXPANSION

In the preview flag, execute, reload, set-query... binds, sk will expand placeholders. this is the secret sauce, bestie:

  • {} (or --replstr if used) will be expanded to the current item.
  • {q} (or {cq} for legacy reasons) will be expanded to the current query input.
  • {+} will be expanded to either the currently selected items in multi-select mode, or the current item in single-select.
  • {n} will be expanded to the index of the current item.
  • {+n} will be expanded to the index(es) of the corresponding {+} item(s).
  • {FIELD_INDEX_EXPRESSION} will be expanded to the field index expression run against the current item.
  • {+FIELD_INDEX_EXPRESSION} will be expanded to the field index expression run against the {+} item(s).

🧮 Field index expression

skim will expand some expressions between {..}. It will expand to the corresponding fields, separated by the --delimiter|-d option (see there for details). yes, this is giving “tiny language inside your picker”:

  • {n} will be the n-th field.
  • {n..m} will be the fields from n to m, inclusive, separated by a space
  • {-n} will be the n-th, starting from the end, -1 will be the last field etc.

🌱 ENVIRONMENT VARIABLES

🍓 SKIM_DEFAULT_COMMAND

If set, skim will collect items with this command if no input is piped in. If not set, defaults to find . on unix-like systems and dir /s /b /A:-D on Windows. noted, bestie — those defaults are exact. ✨

🌸 SKIM_DEFAULT_OPTIONS

Will be parsed and used as default options. Example: --reverse --multi

🎀 SKIM_OPTIONS_FILE

If the variable is set to the path of an existing file, the contents of this file will be parsed and used as default options. It supports # as a comment start, which can be escaped using ##. Example:

# Preview
--preview 'echo {}'
--preview-window 'left:30%' # Preview window
--reverse
--prompt '## '

🦋 NO_COLOR

If set to a non-empty value, will disable coloring. no color, no problem 💅

🎨 THEME 🎨

ok so you can ~theme~ this whole thing, and here's the whole menu, bestie:

  • none — the base color scheme, plain and simple
  • molokai — molokai 256color
  • light — light 256color
  • 16 — dark base16 theme
  • bw — black & white theme, for the minimalists 💅
  • dark | default — dark 256color, and yes this is the default value
  • all 4 catppuccin variants — the whole collection, we love a theme family:
    • catppuccin-latte
    • catppuccin-macchiato
    • catppuccin-frappe
    • catppuccin-mocha

🌈 the color names you can use

these are the little keywords that say what you're coloring:

  • normal (or an empty string) — normal text
  • matched (or hl) — matched text, the stuff you searched for
  • current (or fg+) — current line foreground
  • bg+ — current line background (special case: it always sets background, no notes)
  • current_match (or hl+) — matched text in the current line
  • query — query text
  • spinner — spinner character
  • info — info text (the match count)
  • prompt — prompt text
  • cursor (or pointer) — cursor/pointer, main character energy
  • selected (or marker) — selected item marker
  • header — header text
  • border — border lines
  • separator — the horizontal separator (independent of borders and headers, she does her own thing)
  • scrollbar — item list scrollbar thumb

🖌️ picking the part

adding -fg, _fg, -bg, _bg, -underline, _underline sets the corresponding part of the color. for instance, normal-fg (or simply fg) will set the foreground normal color. easy.

🎯 color formats

  • 0-255 — ANSI terminal color
  • #rrggbb — 24-bit color, fancy

✨ attrs

  • x | regular — resets the modifiers, use it before the others (order matters bestie, do it first)
  • b | bold
  • u | underline
  • c | crossed-out
  • d | dim
  • i | italic
  • r | reverse

🍓 the example, look at her go

--color '16,normal-fg:0+bold,matched-fg:#ffffff+u,cursor-bg:#deadbe'

this will start with the base 16 theme and override it with a bold ANSI color 0 foreground (black), a hex ffffff (full white) underlined foreground for matched parts and a #deadbe (pale rose, apparently 🎀) cursor background. iconic behavior, no notes.

📡 LISTEN/REMOTE 📡

skim can be controlled from other processes, using the --listen (and optionally --remote) flags. yes she's remote-controllable, she's that girl.

to achieve this, run the server instance using sk --listen optional_address (the address defaults to sk). it will then start listening on a named socket for instructions.

to send instructions, you can use sk --remote optional_address or any other tool that allows us to interact with such sockets, such as socat on linux:

echo 'ToggleIn' | socat -u STDIN ABSTRACT-CONNECT:optional_address

instructions correspond to skim's Actions and need to be sent in Ron format. when using sk --remote, pipe in action chains (see the KEYBINDS section), for instance:

echo 'up+select-row' | sk --remote optional_address

🚪 EXIT CODES 🚪

  • 0 — success slay 💖
  • 1 — no match
  • 130 — interrupt (ctrl-c or esc)
  • others — error 😭

🏷️ VERSION 🏷️

v5.9.0

and that's the whole page babes 🫶 — this was sk 5.9.0, page sk(1), delivered fresh from that exact source and version. go forth and fuzzy-find something gorgeous ✨💅

📦 where this page comes from