Skip to main content

FAQ

General​

How is cli-expander different from Espanso?​

cli-expander is terminal-native — forms render inline in your terminal via Cursive TUI, not as GUI popups. It's designed for CLI-first workflows, with shell plugin integration (Bash/Zsh/Fish) and tmux support. Espanso is a GUI text expander focused on desktop applications.

Does it work on macOS or Windows?​

Currently Linux only. The system-wide mode relies on evdev and uinput (Linux kernel subsystems). Shell plugins and CLI expansion work on any Unix-like system, but keyboard detection and injection are Linux-specific.

Is it free? Is there a paid version?​

Yes, cli-expander is 100% free and open source under the MIT license. There is no paid version.

Does it phone home? Is there telemetry?​

No. All processing is local. cli-expander has no analytics, no telemetry, and no network requests during normal operation.

Installation and Setup​

How do I upgrade?​

Rebuild from source using git pull && cargo build --release and copy the binary. Match files are backward-compatible across versions.

Can I install it without Rust?​

Currently, building from source is the only option. Pre-built binaries may be available in future releases.

Do I need fzf?​

No, fzf is optional. It enables the interactive trigger search in the Bash plugin (Ctrl+F/Alt+F). Basic expansion and forms work without it.

Usage​

Why doesn't :trigger[Space] work in my shell?​

Make sure you've sourced the shell plugin in your ~/.bashrc, ~/.zshrc, or ~/.config/fish/config.fish. The plugin intercepts Space to check for triggers.

Can I use cli-expander in pipes and scripts?​

Yes, but only for text replacement. Forms require an interactive terminal. For non-interactive use:

echo ":hello" | ce expand
ce --batch ":hello"

How do I see all my triggers?​

ce list
ce search "keyword"

Can I share match files between computers?​

Yes! Put your ~/.config/cli-expander/ directory in a git repo or sync it with Dropbox/Google Drive. Match files are plain YAML.

My trigger matches inside words — how do I prevent that?​

Add word: true to only match at word boundaries, or use a prefix like : to make triggers unlikely to appear in normal text.

Troubleshooting​

The form doesn't open, nothing happens​

Forms need an interactive terminal. Try running ce :trigger directly (not via pipe or SSH without TTY). Check that your TERM variable is set and your terminal is fully featured.

ce command not found​

The binary isn't in your PATH. Run which ce or find ~/.local/bin -name ce. Add the directory to your PATH.

YAML file is not being loaded​

Check that:

  • The file has a .yml or .yaml extension
  • The file doesn't start with _ (underscore-prefixed files are ignored)
  • The YAML syntax is valid (try yamlint or a YAML validator)

I changed a match file but nothing updates​

cli-expander reads match files on each invocation. If you're using the shell plugin, try exec bash to reload the shell. If using system-wide mode, restart the daemon.

Features​

Can I use it for GUI apps?​

Yes, through system-wide mode — using evdev for keyboard detection and uinput for text injection. This works in any application on Linux, including browsers and editors.

Does it support images?​

No. cli-expander is text-only. For image expansion, consider Espanso or other GUI expanders.

Can I use regex triggers?​

Currently cli-expander uses exact string matching. Regex support is on the roadmap.

Is there a package manager / community package repository?​

Not yet. Match files are shared via git repositories or directly as YAML files. A package system is under consideration.