Introduction

Like IntelliSense, but for shells!

Welcome to the official guide for IntelliShell. If you find yourself constantly searching your shell history for that one-trick awk command, forgetting the exact flags for tar or ffmpeg, or re-typing long commands with only minor changes, then you've come to the right place.

IntelliShell is a smart command-line bookmark manager designed to solve these exact problems. It helps you save, find, organize, and reuse your most valuable commands directly within your terminal, turning your shell history from a chaotic log into a structured, searchable library.

Key Features

IntelliShell is built with a focus on efficiency and seamless integration:

• Instant Access: Find and execute commands in seconds with an interactive search UI, triggered by a simple keybinding (ctrl+space).

• Dynamic Commands: Create powerful command templates using {{variables}}. IntelliShell will prompt you to fill them in on the fly, making your commands reusable for any scenario.

• Effortless Organization: Use descriptions and hashtags (#work, #gcp) to categorize your commands, making them easy to filter and find.

• Workspace-Specific Commands: Automatically load and prioritize workspace-specific commands from .intellishell files in your current workspace.

• Sync & Share: Export your command library to a file, an HTTP endpoint, or a GitHub Gist to back it up or share it with your team.

• Extensible Knowledge: Instantly boost your library by fetching and importing command examples from the community-driven tldr pages.

How to Use This Book

This documentation is structured into three main sections to help you find what you need quickly:

• Quick Start If you're new to IntelliShell, start here.

  The guide contains step-by-step tutorials that will take you from installation and basic usage to mastering advanced workflows like shell integration and command syncing.

• Configuration This section is your reference for personalizing IntelliShell.

  Learn how to change keybindings, customize the theme, and even fine-tune the search-ranking algorithms to make the tool truly your own.

• Command Line Tool Here you will find a detailed, technical breakdown of every command.

  It's the perfect place for quick lookups when you need to know exactly which flags are available or what a specific option does.

Ready to get started? Let's head over to the Installation page.

Installation

Welcome to the IntelliShell installation guide. Getting IntelliShell running on your system involves two main steps:

1. Download the Binary: This places the intelli-shell executable on your machine.
2. Configure Shell Integration: This involves updating your shell's profile (e.g., ~/.bashrc, ~/.zshrc) to source the init output that enables the interactive keybindings (ctrl+space, etc.).

The easiest way to perform both steps is with the official installer script.

Method 1: Installer Script

This is the fastest way to get started. The script automatically handles downloading the correct binary for your system and setting up the shell integration.

If you don't want the script to update the profile files, you can set INTELLI_SKIP_PROFILE=1 environment variable before installing.

Linux, macOS & Windows on sh-compatible shell (Bash, Zsh, Fish, Git Bash)

curl -sSf https://raw.githubusercontent.com/lasantosr/intelli-shell/main/install.sh | sh

After installing it on any shell, it should work in all of them.

Windows (PowerShell)

irm https://raw.githubusercontent.com/lasantosr/intelli-shell/main/install.ps1 | iex

After installing it with powershell, it should also work on cmd (without hotkeys).

The Microsoft Visual C++ Redistributable is required. You can download it from Microsoft's official site. You may also need to run Set-ExecutionPolicy RemoteSigned -Scope CurrentUser if you haven't run remote scripts before.

Method 2: Building from Source

If you have the Rust toolchain installed, you can build and install the binary directly from crates.io.

cargo install intelli-shell --locked

To enable hotkeys integration, additional steps are required:

Customizing Shell Integration

These variables customize the keybindings to integrate with IntehliShell. They should be set in your shell's profile file (e.g., ~/.bashrc, ~/.zshrc) before the line that sources the IntelliShell init command.

• INTELLI_SEARCH_HOTKEY: Overrides the default ctrl+space hotkey for searching commands.
• INTELLI_BOOKMARK_HOTKEY: Overrides the default ctrl+b hotkey to bookmark a command.
• INTELLI_VARIABLE_HOTKEY: Overrides the default ctrl+l hotkey for replacing variables.
• INTELLI_SKIP_ESC_BIND=1: Prevents IntelliShell from binding the esc key to clear the current line in the terminal.

For keybinding syntax, refer to your shell's documentation (bindkey for Zsh, bind for Bash). For example, to change the search hotkey in Bash, you would add the line export INTELLI_SEARCH_HOTKEY=\\C-t to your .bashrc.

Verify Your Installation

After installing, open a new terminal session to ensure the changes are loaded. You can verify that the intelli-shell binary is working by running:

intelli-shell --version

If the command is found and you can use shortcuts (if configured), you are ready to go! Let's move on to Basic Usage.

Basic Usage

IntelliShell is designed to be an integral part of your daily shell workflow. Instead of manually typing intelli-shell commands, you'll primarily interact with it through a set of convenient hotkeys directly from your command line.

The core idea is simple: type a command, bookmark it, and then quickly find and reuse it later—all without leaving your terminal prompt.

Core Hotkeys

By default, IntelliShell sets up three main hotkeys. These are the primary ways you will interact with the tool.

• Search Ctrl+Space: This is your main entry point. It opens an interactive search UI to find your bookmarked commands. If you have text on the command line, it will be used as the initial search query.

• Bookmark Ctrl+B: When you've typed a command you want to save, this key opens a UI to bookmark it. The current text on your command line will be pre-filled as the command to be saved.

• Variable Replace Ctrl+L: If the command on your line contains {{variables}}, this key opens the variable replacement UI to fill them in without needing to save the command first.

• Clear Line Esc: As a convenience, this key is bound to clear the entire command line. This can be disabled if it conflicts with your existing terminal habits.

📝 Note: These hotkeys are fully customizable. See the Installation chapter for details on how to change them.

Your First Bookmark

Let's walk through a common use case: saving a command, searching for it, and running it again with new values.

1. Write a command

   Type a command you find yourself using often. For this example, we'll use a docker command with a placeholder for the image name. In your terminal, type:

   docker run -it --rm {{image}}
   

2. Bookmark it

   With the command still on the line, press Ctrl+B. The bookmarking UI will appear. You can add more details here:

   • Alias: A short, memorable name. Let's use dr. This allows for quick lookups later.
   • Description: A brief explanation. Let's add Run a temporary docker image #docker.

   Press Enter to save the bookmark.

3. Search for it

   Later, when you need that command, type its alias dr and press Ctrl+Space. Because there's only one command matching the dr alias, the search UI is skipped, and you are taken directly to the variable replacement screen.

   • Type ubuntu:latest and press Enter.

   IntelliShell replaces the variable and places the final, ready-to-run command onto your shell prompt:

   docker run -it --rm ubuntu:latest
   

   Just press Enter one last time in your shell to execute it!

4. Re-run with new values

   Now if you need to run the same command, but with the debian image, there's no need to re-type anything.

   • Use the Up Arrow key in your shell to recall the last command
   • With docker run -it --rm ubuntu:latest on the line, press Ctrl+Space
   • IntelliShell recognizes the command's original template and shows it as the top result, so you can select it and provide a new value for the {{image}} variable

Organize with Hashtags

Hashtags are a powerful way to categorize and quickly filter your commands. Any word in a command's description that starts with a # symbol is treated as a searchable tag.

In the previous example, we added the #docker tag. Let's bookmark another command to see how this works.

1. Bookmark another command

   Type git checkout {{branch}} into your terminal, press Ctrl+B, and add a description with a hashtag like Checkout a git branch #git.

2. Discover and filter by hashtag Now you have commands tagged with #docker and #git. You can use these to filter your search.

   • Clear your command line, type #, and press Ctrl+Space
   • The search UI will suggest all the hashtags you've used, selecting one will instantly filter your command list

💡 Tip: Hashtag discovery is cumulative and considers your entire query. For example, if you search for docker #compose and then type # again, the suggestions will only include tags that appear on commands matching "docker" and already tagged with #compose. This lets you progressively narrow your search.

Populating Your Library with tldr

If you're getting started or need a quick example for a new tool, you can populate IntelliShell with commands from the community-driven tldr pages project.

1. Fetch tldr pages

   Run the fetch command to download command examples for any tool.

   intelli-shell tldr fetch -c tar
   

   This will import useful command templates into a separate tldr space, which you can choose to include or exclude from your searches.

2. Find and use a tldr command

   Forgot how to list the contents of a tar archive?

   • Type tar into the command line and press Ctrl+Space
   • You'll see a list of tldr examples for tar
   • Find the one for listing contents, select it, fill in the {{path/to/file.tar}} variable, and run it

💡 Tip: The fetch command is highly configurable, allowing you to import pages for specific commands or categories. For a full list of options, see the fetch command reference.

Now that you've mastered the basics, let's dive deeper into how to use variables effectively in the next chapter: Using Variables.

Using Variables

The true power of IntelliShell lies in its ability to create reusable command templates. Instead of saving a static command like docker run ubuntu:latest, you can create a dynamic version: docker run {{image}}.

We call these dynamic placeholders variables. When you execute a command with variables, IntelliShell will prompt you to provide values for them on the fly, turning a specific command into a versatile, reusable tool.

Basic Syntax

A variable is any text enclosed in double curly braces: {{variable_name}}.

echo "Hello, {{user}}!"

When you use this command, IntelliShell's variable replacement UI will open, prompting you for a value for the user variable. The value you provide will be stored as a suggestion for the next time you use a {{user}} variable in an echo command.

Secret Variables

Some variables, like comments, API tokens or passwords, shouldn't be saved in your suggestion history. You can mark a variable as secret by enclosing it in an extra set of curly braces: {{{secret_variable}}}.

curl -u user:{{{password}}} https://api.example.com/data

When you fill in a secret variable:

• The value is used in the command just once
• It is never saved to your suggestion history
• If a matching environment variable (e.g., PASSWORD) exists, IntelliShell will suggest using the variable itself (e.g., $PASSWORD or $env:PASSWORD) in the final command, preventing the secret value from ever being exposed in plain text

Providing Default Suggestions

You can provide a list of predefined options for a variable directly in its definition using the pipe (|) character. These options will appear as "derived" suggestions in the UI.

This is perfect for commands where the input is one of a few known values, like a subcommand.

# Provides 'up', 'down', and 'logs' as initial suggestions
docker-compose {{up|down|logs}}

Formatting Input with Functions

IntelliShell can automatically format the text you enter for a variable before inserting it into the final command. Functions are appended to the variable name, separated by colons (:).

Syntax: {{variable_name:function1:function2}}

For example, a common task is creating a git branch name from a description. You can automate the formatting:

# Input: "My New Feature" -> Output: "feature/my-new-feature"
git checkout -b feature/{{{description:kebab}}}

Here are the available functions:

Functions are applied from left to right.

How Suggestions Are Managed

IntelliShell is smart about how it stores and suggests values for your variables. Suggestions are shared based on two factors:

1. The Root Command: The first word of your command (e.g., git, docker).
2. The Variable's Identity: The text inside the {{...}} braces, excluding any formatting functions.

This means:

• Shared Suggestions: Using {{image}} for both docker run and docker rmi will use the same list of image suggestions, which is usually what you want. The same applies if you use {{image|container}} and {{image}}; suggestions for image will be shared.

• Separate Suggestions: To keep suggestions separate, use different variable names. For example, you can have two SSH commands with different suggestion lists by using ssh {{prod_server}} and ssh {{staging_server}}.

This system gives you fine-grained control over which commands share suggestion histories, helping you keep different contexts neatly organized.

Now that you can create powerful, reusable command templates, let's look at how to manage commands that are specific to your current workspace in Workspace-Specific Commands.

Workspace-Specific Commands

While your global command library is perfect for personal, frequently used commands, many tasks are specific to a particular workspace or repository. IntelliShell addresses this with .intellishell files, a simple way to define and share commands that are relevant only to your current working directory.

How It Works

When you trigger a search, IntelliShell automatically looks for a file named .intellishell in the current directory. If it doesn't find one, it searches parent directories until it reaches a .git directory or the filesystem root.

If an .intellishell file is found, its commands are loaded into a temporary, session-only library. These commands are given top priority in search results, appearing above your personal and tldr commands.

Note: You can temporarily disable this feature by setting the INTELLI_SKIP_WORKSPACE=1 environment variable. If this variable is set, IntelliShell will not search for or load any .intellishell file.

Key Behaviors

• Context-Aware: Commands are only available when you are working inside that workspace's directory tree
• Session-Only: Workspace commands are not saved to your permanent database. They are loaded fresh for each session
• Top Priority: Workspace-specific commands always appear at the top of your search results, making them easy to find
• Version Controllable: Since it's a plain text file, you can commit .intellishell to your Git repository to share common workspace commands with your entire team

Use Cases

Workspace-specific commands are ideal for:

• Team Onboarding: New team members can instantly access common build, test, and deployment commands
• Complex Workflows: Document and share multi-step processes, like database migrations or release procedures
• Discoverability: Make workspace-specific scripts and tools easily discoverable without needing to ls through a scripts/ directory, just hit Ctrl+Space to discover them

File Format

The .intellishell file uses the same simple text format as the import and export commands. Any commented line (#) before a command is treated as its description.

Here is an example .intellishell file for a web project:

#!intelli-shell

# Run the development server
npm run dev

# Build the project for production #build
npm run build

# Run all linters and formatters #lint #test
npm run lint && npm run format

# Run end-to-end tests with playwright #test
npx playwright test

Between your personal library and workspace-specific files, you have a powerful system for managing commands. Let's now see how you can back up, restore, and share your personal commands across different machines in Syncing and Sharing.

Syncing and Sharing

IntelliShell makes it easy to back up your command library, share it with teammates, or sync it across multiple machines. This is all handled by the intelli-shell export and intelli-shell import commands.

You can export your commands to a local file, a remote HTTP endpoint, or a GitHub Gist, and then import them elsewhere. The tool automatically detects the location type (file, http, or gist) based on the provided string, but you can also specify it explicitly with the --file, --http, or --gist flags.

Commands are stored in a simple, human-readable text format. Any commented lines (#) directly preceding a command are treated as its description, making the files easy to edit by hand.

# A multi-line description for a command
# with a #hashtag for organization.
docker ps --format "table {{.ID}}\t{{.Image}}\t{{.Status}}"

# Prints the current working directory
pwd

Local Backup & Restore

The simplest way to back up your commands is by exporting them to a local file. This creates a portable snapshot of your library that you can store or move to another machine.

1. Backing Up to a File

To export all your user-defined commands into a single file, provide the file path to the export command.

intelli-shell export my_commands.bak

2. Restoring from a File

To restore your commands from a backup file, provide the file path to the import command.

intelli-shell import my_commands.bak

Syncing with a GitHub Gist

Using a GitHub Gist is a flexible way to manage your command library. You can use a private Gist for personal cloud sync across your devices, or a public Gist to share useful commands with the community. It's also an effective method for sharing project-related commands with teammates.

Supported Gist Locations

IntelliShell can understand various Gist location formats:

• Full URL: A standard URL to a Gist (e.g., https://gist.github.com/user/gist-id)
• Shorthand ID: Just the unique ID of the Gist (e.g., b3a462e23db5c99d1f3f4abf0dae5bd8)
• ID and File: You can target a specific file within a Gist by appending the filename (e.g., gist-id/commands.sh)

1. Exporting to a Gist

Before you can export to a Gist, you must first create it on GitHub to get its unique ID. IntelliShell updates existing Gists; it does not create new ones.

When specifying the Gist location:

• Using a URL: IntelliShell automatically detects that the location is a Gist
• Using an ID: If you use just the Gist ID, you must add the --gist flag to distinguish it from a local file with the same name

# The --gist flag is required when using only the ID
intelli-shell export --gist {{gist-id}}

Gist Authentication: To export to a Gist, you need a GitHub Personal Access Token with gist scope. You can set this using the GIST_TOKEN environment variable or in your config.toml file. For more details, see the Configuration chapter.

2. Importing from a Gist

Similarly, you can import from the Gist on another machine to sync your commands.

# The --gist flag is also required here when using only the ID
intelli-shell import --gist {{gist-id}}

Tip: Set a Default Gist

You can set a default Gist ID in your config.toml file. Once configured, you can sync with even shorter commands, as IntelliShell will use the default ID when it sees "gist" as the location:

# Export to the default Gist
intelli-shell export gist

# Import from the default Gist
intelli-shell import gist

Syncing with a Custom HTTP Endpoint

If you prefer to host your own command storage, you can configure IntelliShell to sync with any custom HTTP endpoint you control. This is ideal for teams who want to maintain a private, centralized command library on their own infrastructure.

When exporting, IntelliShell sends a PUT request with a JSON payload of your commands. When importing, it can handle either the standard plain text format (Content-Type: text/plain) or a JSON array (Content-Type: application/json). You can also specify custom headers for authentication.

# Export to a private, authenticated endpoint
intelli-shell export -H "Authorization: Bearer {{{private-token}}}" https://my-server.com/commands

# Import from the same endpoint
intelli-shell import -H "Authorization: Bearer {{{private-token}}}" https://my-server.com/commands

Advanced Options

Here are a few more options to customize your import and export workflows.

Filtering Commands

The --filter flag lets you process a subset of commands using a regular expression. This works for both importing and exporting.

# Export only docker commands to a local file
intelli-shell export docker_commands.sh --filter "^docker"

# Import only git commands from a file
intelli-shell import all_commands.sh --filter "^git"

Tagging on Import

When importing commands from a shared source, you can use --add-tag (-t) to automatically organize them.

# Import commands for a specific project, tagging them with #project
intelli-shell import -t project https://gist.githubusercontent.com/user/id/raw/project.sh

Previewing with Dry Run

If you're not sure what a file or URL contains, use the --dry-run flag with the import command. It will print the commands that would be imported to the terminal without actually saving them to your library.

intelli-shell import --dry-run https://example.com/some-commands.sh 

Now that you're familiar with syncing, let's look at how to customize IntelliShell in the Configuration section.

Configuration

IntelliShell is designed to be highly adaptable to your personal workflow and aesthetic preferences. Most of the customization is handled through a single config.toml file, while shell-specific hotkeys are configured using environment variables.

This section will guide you through all the available options to help you make IntelliShell truly your own.

The Configuration File

All settings related to the application's behavior, appearance, and search algorithms are stored in a file named config.toml.

Configuration File Location

IntelliShell first checks if the INTELLI_CONFIG environment variable is set. If it is, the application will load the configuration from that specific file path. This is useful for testing different configurations or managing portable setups.

If the environment variable is not set, IntelliShell falls back to searching in these default locations:

• Linux/macOS: ~/.config/intelli-shell/config.toml
• Windows: %APPDATA%\IntelliShell\Intelli-Shell\config\config.toml

If no configuration file is found, IntelliShell will use its built-in default settings. To get started with customization, you can copy a section from the default configuration file and modify it to your liking. Any setting you don't explicitly define will automatically use its default value.

Configuration Topics

This section is broken down into the following chapters:

• General: A detailed look at the config.toml file structure and its general settings, including data directory, Gist integration, and logging

• Key Bindings: Learn how to customize the keyboard shortcuts used to navigate and interact with the TUI

• Theming: Change the colors, styles, and symbols of the interface to match your terminal's theme

• Search Tuning: An advanced guide to modifying the ranking algorithms that determine how commands and variable suggestions are sorted

Shell Hotkey Configuration

The primary hotkeys that trigger IntelliShell from your command line (e.g., Ctrl+Space) are configured separately via environment variables in your shell's profile (e.g., ~/.bashrc, ~/.zshrc). This is covered in detail in the Installation chapter.

Ready to start customizing? Let's dive into General.

General Settings

This section covers the general configuration options that control the core behavior and appearance of IntelliShell, such as the user interface mode and the location where application data is stored. These settings are located at the top level of your config.toml file.

Data Directory

The data_dir setting specifies the directory where IntelliShell stores its data, including the command database (storage.db3), logs, and other state files.

If you leave this setting as an empty string (""), IntelliShell will use the default system-specific data directory:

• Linux: ~/.local/share/intelli-shell (or $XDG_DATA_HOME/intelli-shell if set)
• macOS: ~/Library/Application Support/org.IntelliShell.Intelli-Shell
• Windows: %APPDATA%\IntelliShell\Intelli-Shell\data

You can specify a custom path to store your data in a different location, such as a synced cloud folder.

# The default directory for application data, such as the stored commands database.
# If this value is left empty, the application will use the system's default data directory:
# - ~/.local/share/intelli-shell (on Linux/macOS, unless overridden by XDG_DATA_HOME)
# - ~/Library/Application Support/org.IntelliShell.Intelli-Shell (on macOS)
# - %APPDATA%\IntelliShell\Intelli-Shell\data (on Windows)
data_dir = ""

Overriding with INTELLI_STORAGE

For more direct control, especially in containerized or portable environments, you can use the INTELLI_STORAGE environment variable. If set, this variable must contain the full path to your database file, not just a directory.

This variable takes precedence over the data_dir setting just for the database, and IntelliShell will use the specified file for all database operations.

# Example for Linux/macOS
export INTELLI_STORAGE="/path/to/my/custom.db3"

Update Checks

This setting controls whether IntelliShell automatically checks for new versions upon startup. When enabled, it helps ensure you are always using the latest version with the newest features and bug fixes.

• check_updates = true (Default): The application will check for updates at startup. If a new version is available, a notification will be shown in the TUI.
• check_updates = false: Disables the automatic update check.

# Whether to check for updates on application startup
check_updates = true

UI Rendering Mode

The inline setting controls how the interactive Terminal User Interface (TUI) is displayed. You can choose between a compact, inline view or an immersive, full-screen experience.

• inline = true (Default): The TUI renders directly below your current shell prompt. This mode is less intrusive and allows you to see your previous commands while you search.

• inline = false: The TUI takes over the entire terminal window, providing a more focused, full-screen experience.

# Determines the rendering mode for the Terminal User Interface (TUI).
# - If `true`, the TUI will appear directly below the shell prompt, integrating seamlessly
# - If `false`, the TUI will take over the entire terminal screen
inline = true

Gist Integration

The [gist] section allows you to configure default settings for importing from and exporting to GitHub Gists. This is useful if you frequently use the same Gist to back up or share your commands.

• id: The ID of your default GitHub Gist. You can find this in the Gist's URL.
• token: A GitHub Personal Access Token with gist scope. This is required for creating or updating private Gists.

# Configuration for the default gist to use when importing or exporting (if no other is explicitly set)
[gist]
# The id of the gist, you can get it from the url after the username
id = ""
# Token to authenticate the API call to GH when exporting
# GIST_TOKEN env variable will take precedence over the config value
token = ""

Search

The [search] section lets you fine-tune the default behavior of the interactive search.

• delay: The time in milliseconds that IntelliShell waits after you stop typing before it starts searching
• mode: The default search algorithm, can be auto, fuzzy, regex, exact, or relaxed
• user_only: If set to true, searches will exclude commands from tldr and .intellishell file

These settings can be toggled on-the-fly within the search UI using the default keybindings ctrl+s and ctrl+o.

# Configuration for the search command
[search]
# The delay (in ms) to wait and accumulate type events before triggering the query
delay = 250
# Specifies the default search mode to be used when initiating a search.
# Possible values are:
# - "auto": An internal algorithm is used to best match common human search patterns
# - "fuzzy": Employs fuzzy matching to find commands that are similar to the input query
# - "regex": Treats the input query as a regular expression, allowing for complex pattern matching
# - "exact": The search will only return commands that precisely match the entire input query
# - "relaxed": Attempts to find the maximum number of potentially relevant commands using broader matching criteria
mode = "auto"
# Whether to search for user commands only by default when initiating a search (excluding tldr and workspace)
user_only = false

Logging

The [logs] section configures the application's logging behavior, which is useful for debugging or monitoring. Note that if the INTELLI_LOG environment variable is set, it will override the settings in this file.

• enabled: Set to true to enable writing logs to a file in the application's data directory
• filter: Controls the verbosity of the logs using tracing-subscriber syntax

# Configuration settings for application logging.
#
# If an `INTELLI_LOG` environment variable exists, it will override the filter and enable logging.
[logs]
# Whether application logging is enabled.
# If set to `true`, the application will write detailed logs to a file within the data directory.
enabled = false
# The log filter to apply, controlling which logs are recorded.
#
# This string supports the `tracing-subscriber`'s environment filter syntax, for example:
# - "info" enables info log level (and above: warn and error)
# - "warn,intelli_shell=debug" enables debug for `intelli_shell` and warn for the rest
filter = "info"

Now that you've configured the application's basic behavior, you can tailor how you interact with it. Let's move on to customizing the Key Bindings.

Key Bindings

Key bindings in IntelliShell are a mix of high-level customizable actions and built-in standard controls. This approach provides flexibility for core actions while maintaining a consistent, hardcoded set of keys for navigation and text editing, many of which follow common terminal and Emacs-like conventions.

⚠️ Terminal Compatibility

Your ability to use certain key combinations depends entirely on your terminal emulator. Some terminals may capture specific hotkeys (like ctrl-space or ctrl-enter) for their own features and will not forward them to IntelliShell. This is particularly common on Windows with terminals like Cmder or older versions of Windows Terminal. If a key binding doesn't work, try a different combination or consult your terminal's documentation.

Customizable Actions

These are the primary actions you can configure in the [keybindings] section of your config.toml file. They handle the main functions of the TUI, like confirming a selection or deleting a command.

The format and a list of available actions are detailed below. Note that if a default binding for a customizable action (like ctrl-d for delete) conflicts with a standard control, the customizable action always takes precedence.

Default Configuration

You can change these bindings by modifying the [keybindings] block in your configuration file.

# Configuration for the key bindings used to interact with the Terminal User Interface (TUI).
# Key bindings map an action within the application to one or more key press combinations.
#
# Each action can be bound to a single key event string or a list of key event strings.
# If a list is provided, pressing any of the listed combinations will trigger the action.
#
# Key event strings are parsed from a simple format:
# - Modifiers (optional, separated by `-` or `+`): `ctrl`, `shift`, `alt`
# - Followed by the key name or character
[keybindings]
# Exit the TUI gracefully
quit = "esc"
# Update the currently highlighted record or item (e.g., edit a command)
update = ["ctrl-u", "ctrl-e", "F2"]
# Delete the currently highlighted record or item
delete = "ctrl-d"
# Confirm a selection or action related to the highlighted record
confirm = ["tab", "enter"]
# Execute the action associated with the highlighted record or item (e.g., run a command)
execute = ["ctrl-enter", "ctrl-r"]
# Toggle the search mode
search_mode = "ctrl-s"
# Toggle whether to search for user commands only or include workspace and tldr's
search_user_only = "ctrl-o"

Standard Controls

These key bindings are not configurable and provide a standard way to navigate lists and edit text. They are always active unless overridden by a customizable action.

List & Tab Navigation

Text Cursor Movement

Text Editing

With your keybindings configured, you can now personalize the application's appearance. Let's dive into Theming.

Theming

IntelliShell's appearance is fully customizable, allowing you to tailor the colors and styles of the Terminal User Interface (TUI) to perfectly match your terminal's color scheme. All theming options are configured within the [theme] section of your config.toml file.

Style Formatting

Styles are defined using a string that combines optional modifiers with an optional color. For example, a style for an important but subdued text might be "bold italic yellow".

Supported Modifiers

You can apply one or more of the following text attributes:

• bold
• dim
• italic
• underline

Supported Colors

Colors can be specified in several formats:

• Named Colors: Standard ANSI colors like black, red, green, dark yellow, etc
• RGB: rgb(15, 15, 15)
• Hexadecimal: #112233
• ANSI 8-bit Index: An integer from 0 to 255 as a string (e.g., "8")
• Default: Use default or an empty string ("") to inherit your terminal's colors

Configuration Options

Here is a breakdown of each available key in the [theme] section.

Default Configuration

# Configuration for the visual theme of the Terminal User Interface (TUI).
#
# Styles are defined using a string that can consist of one or more optional modifiers
# followed by an optional color. Modifiers and colors should be space-separated.
#
# Supported Modifiers: `bold`, `dim`, `italic`, `underline`
#
# Supported Color Formats:
# - Keep the original terminal color (no ANSI escape codes): "default" or an empty string (`""`)
# - Named colors (standard ANSI): "black", "red", etc.
# - RGB color value: "rgb(15, 15, 15)"
# - Hexadecimal color value: "#112233"
# - ANSI 8-bit indexed color (integer string from 0 to 255): "8", "13", etc.
[theme]
# The primary style used for main elements, like selected items or important text
primary = "default"
# The secondary style used for less prominent elements, like unselected items
secondary = "dim"
# An accent style used to highlight specific elements, like aliases or keywords
accent = "yellow"
# The style used for comments or explanatory text
comment = "italic green"
# The style used for errors
error = "dark red"
# The background color for the highlighted item in a list. Use "none" for no background color
highlight = "dark gray"
# The string symbol displayed next to the highlighted item
highlight_symbol = "» "
# The primary style applied specifically to a highlighted item
highlight_primary = "default"
# The secondary style applied specifically to a highlighted item
highlight_secondary = "dim"
# The accent style applied specifically to a highlighted item
highlight_accent = "yellow"
# The comments style applied specifically to a highlighted item
highlight_comment = "italic green"

Sample Themes

The IntelliShell repository includes several pre-made themes to get you started.

Gruvbox

A theme inspired by the popular Gruvbox color scheme, featuring a warm, retro feel.

[theme]
primary = "#ebdbb2"
secondary = "#a89984"
accent = "bold #b8bb26"
comment = "italic #928374"
error = "bold #fb4934"
highlight = "#458588"
highlight_symbol = "» "
highlight_primary = "#ebdbb2"
highlight_secondary = "dim #ebdbb2"
highlight_accent = "bold #fabd2f"
highlight_comment = "italic dim #ebdbb2"

Nord

A theme based on the arctic, north-bluish color palette of Nord.

[theme]
primary = "#eceff4"
secondary = "#81a1c1"
accent = "bold #a3be8c"
comment = "italic #4c566a"
error = "bold #bf616a"
highlight = "#434c5e"
highlight_symbol = "❄ "
highlight_primary = "#eceff4"
highlight_secondary = "dim #d8dee9"
highlight_accent = "bold #ebcb8b"
highlight_comment = "italic #d8dee9"

Solarized

A theme that implements the balanced and functional Solarized color palette.

[theme]
primary = "#93a1a1"
secondary = "#657b83"
accent = "bold #d33682"
comment = "italic #586e75"
error = "bold #dc322f"
highlight = "none"
highlight_symbol = "→ "
highlight_primary = "bold #fdf6e3"
highlight_secondary = "#859900"
highlight_accent = "bold #cb4b16"
highlight_comment = "italic #657b83"

Dracula

A theme based on the dark and modern Dracula color scheme.

[theme]
primary = "#f8f8f2"
secondary = "#6272a4"
accent = "bold #50fa7b"
comment = "italic #bd93f9"
error = "bold #ff5555"
highlight = "#44475a"
highlight_symbol = "◆ "
highlight_primary = "#f8f8f2"
highlight_secondary = "dim #f8f8f2"
highlight_accent = "bold #ff79c6"
highlight_comment = "italic #bd93f9"

Now that your interface looks just right, you can fine-tune how it behaves. Let's move on to Search Tuning.

Search Tuning

IntelliShell provides advanced control over its search-ranking algorithms, allowing you to fine-tune how commands and variable suggestions are sorted to better match your personal workflow. These settings are located in the [tuning.commands] and [tuning.variables] sections of your config.toml file.

The ranking system for both commands and variables works by assigning points from different sources (like text relevance or usage history) and calculating a final weighted score. By adjusting the points allocated to each source, you can influence which factors are more important in the search results.

Command Search Tuning

The final score for a searched command is a weighted sum of points from three sources: how well the text matches the query, how often the command has been used, and the directory where it was last used.

# Configuration to tune the command search ranking algorithm.
#
# The final score for a command is a weighted sum of points from three sources:
# 1. Usage Score: How often the command has been globally used
# 2. Path Score: Where the command has been used before
# 3. Text Relevance: How well the command's text matches the search query (if any)
[tuning.commands]
# Total points assigned to the global usage of a command
usage.points = 100

# Total points assigned for matching any usage on a relevant path
path.points = 300
# Weights applied to a command path points based on where it was used
path.exact = 1.0
path.ancestor = 0.5
path.descendant = 0.25
path.unrelated = 0.1

# Total points assigned to the normalized text relevance score
text.points = 600
# The weight for the command's `cmd` field in the text search
text.command = 2.0
# The weight for the command's `description` field in the text search
text.description = 1.0

# --- "auto" Mode Specific Tuning ---
# Multiplier for high-confidence prefix matches
text.auto.prefix = 1.5
# Multiplier for standard "all words must match" fuzzy results
text.auto.fuzzy = 1.0
# Multiplier for lower-confidence "any word can match" relaxed results
text.auto.relaxed = 0.5
# A boost multiplier to add when the search term matches the start of a command
text.auto.root = 2.0

Command Scoring Parameters

"Auto" Mode Specific Tuning

These settings only apply when the search mode is set to "auto". They control how much weight is given to different kinds of text matches to produce more intuitive results.

Variable Suggestion Tuning

When you replace variables in a command, IntelliShell suggests previously used values. The ranking of these suggestions is determined by a score calculated from two sources: the context of other variables in the command and the path where the value was used. Total usage count is used as a tie-breaker.

# Configuration to tune the variables suggestion ranking algorithm.
#
# The final score for a variable suggestion is a weighted sum of points from two sources:
# 1. Context Score: Other variable values already selected to the command
# 2. Path Score: Where the value has been used before
# The total usage will be used as a tie-breaker if the same points are scored
[tuning.variables]
# Total points assigned for matching contextual information (e.g., previous variables values)
context.points = 700

# Total points assigned for matching any usage on a relevant path
path.points = 300
# Weights applied to a variable path score based on where it was used
path.exact = 1.0
path.ancestor = 0.5
path.descendant = 0.25
path.unrelated = 0.1

Variable Scoring Parameters

This concludes the configuration guide. With your setup perfectly tuned, let's dive into the detailed breakdown of each Command Line Tool.

Command Line Tool Reference

While IntelliShell is designed for seamless interactive use through shell hotkeys, it also features a comprehensive command-line interface (CLI) for scripting, automation, and direct data management. This section provides a detailed reference for every command and its available options.

The basic structure for any command is:

intelli-shell <COMMAND> [ARGS]

Commands

Here is a summary of all available commands. Each command is detailed on its own page.

Interactive Mode Flags

Several commands (new, search, replace) can be run either non-interactively with arguments or through the TUI by using the -i or --interactive flag. When in interactive mode, you can force a specific rendering style:

• -l, --inline: Forces the TUI to render inline, below the prompt
• -f, --full-screen: Forces the TUI to render in full-screen mode

new

The new command bookmarks a new command in your IntelliShell library.

While commands are typically bookmarked interactively using the ctrl+b hotkey, this command provides a non-interactive way to add new entries. This is particularly useful for scripting, batch-importing from other tools, or when you want to add a command without breaking your terminal flow.

Usage

intelli-shell new [OPTIONS] [COMMAND_STRING]

Arguments

• COMMAND_STRING The command to be stored. This argument is mandatory unless you are running in interactive mode (-i).

  ⚠️ Note: Be mindful of shell expansion. It is best practice to wrap the command string in single quotes (') to ensure special characters like $ or & are preserved exactly as intended.

Options

• -a, --alias <ALIAS>

  Sets an alias (a short, memorable name) for the command.

• -d, --description <DESCRIPTION>

  Provides a detailed description for the command. You can include hashtags (#tag) here for organization.

• -i, --interactive

  Opens the interactive TUI to bookmark the command.

• -l, --inline

  If in interactive mode, forces the TUI to render inline below the prompt.

• -f, --full-screen

  If in interactive mode, forces the TUI to render in full-screen mode.

Examples

1. Bookmark a Simple Command

To save a basic command without any extra details:

intelli-shell new 'echo "Hello, IntelliShell!"'

2. Add a Command with Full Details

To save a command template with an alias and a descriptive tag:

intelli-shell new 'docker run -it --rm {{image}}' --alias 'dr' --description 'Run a temporary docker image #docker'

3. Launch the Interactive UI with a Pre-filled Command

To open the interactive bookmarking window with the command already filled in, allowing you to add the alias and description in the TUI:

intelli-shell new 'git checkout {{branch}}' --interactive

search

The search command finds stored commands based on a query.

By default, this command performs a non-interactive search and prints the matching commands directly to your terminal's standard output. To open the interactive search TUI (the behavior typically associated with the ctrl+space hotkey), you must use the -i or --interactive flag.

Usage

intelli-shell search [OPTIONS] [QUERY]

Arguments

• QUERY

  The search query used to filter commands.

Options

• -m, --mode <MODE>

  Specifies the search algorithm to use, overriding the default set in your configuration file. See the "Advanced Search Syntax" section below for syntax specific to auto and fuzzy modes.

  • auto: Uses an internal algorithm to best match common search patterns.
  • fuzzy: Finds commands that are similar to the query using special syntax.
  • regex: Treats the query as a regular expression for complex pattern matching.
  • exact: Returns only commands that precisely match the entire query.
  • relaxed: Broadens the search to find the maximum number of potentially relevant commands.

• -u, --user-only

  If set, the search will exclude commands imported from tldr pages.

• -i, --interactive

  Opens the interactive TUI to search and select a command.

• -l, --inline

  When used with --interactive, forces the TUI to render inline, below the prompt.

• -f, --full-screen

  When used with --interactive, forces the TUI to render in full-screen mode.

Advanced Search Syntax

The auto and fuzzy search modes support special characters to give you more control over the results.

Auto Mode Syntax

In auto mode, you can exclude results containing a specific word by prefixing it with !.

• Negated Term: !word

  Excludes commands that contain word. For example, docker !test will find commands matching "docker" but not "test".

Fuzzy Mode Syntax

fuzzy mode provides a powerful syntax for fine-grained matching. All terms in a query are space-separated and treated as a logical AND, unless grouped by the | (OR) operator.

Examples

1. Open the Interactive Search

To launch the TUI, you must use the --interactive flag.

intelli-shell search --interactive

2. Perform a Non-Interactive Search

To search for commands matching "docker" and print them to the console:

intelli-shell search docker

3. Non-Interactive Search with Options

To find only your custom commands that exactly match "docker":

intelli-shell search -m exact --user-only docker

4. Open the Interface in Full-Screen Mode

To launch the interactive TUI and force it into full-screen mode:

intelli-shell search -i --full-screen

replace

The replace command populates variables within a command string. Its primary function is to take a command template containing placeholders (e.g., {{variable}}) and fill them in, either through command-line arguments or an interactive prompt.

This is the underlying command that powers variable substitution when you select a command from the search UI or use the ctrl+l hotkey.

Usage

intelli-shell replace [OPTIONS] [COMMAND_STRING]

Arguments

• COMMAND_STRING The command template containing variables to be replaced. If this argument is omitted or set to -, the command will be read from standard input, allowing for piping.

Options

• -e, --env <KEY[=VALUE]>

  Assigns a value to a variable. This option can be used multiple times for multiple variables.

  • If specified as key=value, it directly assigns the value.
  • If only a key is provided (e.g., --env api-token), IntelliShell will read the value from a corresponding environment variable (e.g., API_TOKEN).

• -E, --use-env

  Automatically populate any remaining variables from their corresponding environment variables. This is a broader version of --env <KEY>, giving access to all environment variables without listing them explicitly. Variable names are converted to SCREAMING_SNAKE_CASE to find a matching environment variable (e.g., {{http-header}} maps to HTTP_HEADER).

  This is always enabled on interactive mode, where variables will be presented as options.

• -i, --interactive

  Opens the interactive TUI to fill in the variables.

• -l, --inline

  When used with --interactive, forces the TUI to render inline.

• -f, --full-screen

  When used with --interactive, forces the TUI to render in full-screen mode.

Examples

1. Basic Non-Interactive Replacement

Provide values for variables directly on the command line.

intelli-shell replace 'echo "Hello, {{name}}!"' --env name=World
# Output: echo "Hello, World!"

2. Using Standard Input (Piping)

Pipe a command template into replace to have its variables filled.

echo 'curl -H "Auth: {{token}}"' | intelli-shell replace --env token=xyz123
# Output: curl -H "Auth: xyz123"

3. Populating from Environment Variables

Use existing environment variables to populate command templates.

# Set an environment variable
export FILENAME="report.pdf"

# Use the --use-env flag to automatically find and replace {{filename}}
intelli-shell replace 'tar -czvf archive.tar.gz {{filename}}' --use-env
# Output: tar -czvf archive.tar.gz report.pdf

4. Launching the Interactive UI

If you prefer to fill in variables using the TUI, use the --interactive flag.

intelli-shell replace 'scp {{file}} {{user}}@{{host}}:/remote/path' -i

This will open an interactive prompt asking you to provide values for file, user, and host.

export

The export command allows you to share or back up your user-defined commands by writing them to an external location. This is useful for moving your library between machines, sharing it with teammates, or integrating it with version control.

By default, commands are exported in a simple, human-readable format, but the primary use case is to create backups or share your library.

📝 Note: This command only exports your personal, bookmarked commands. Examples fetched from tldr pages or workspace commands from .intellishell file are not included.

Usage

intelli-shell export [OPTIONS] [LOCATION]

Arguments

• [LOCATION]

  Specifies the destination for the exported commands. This can be a file path, an HTTP(S) URL, or a GitHub Gist ID/URL. If omitted or set to -, the output is written to standard output (stdout), which is useful for piping to other tools.

  • File: intelli-shell export ./my_commands.json
  • HTTP: intelli-shell export https://my-server.com/api/commands
  • Gist: intelli-shell export https://gist.github.com/user/1a2b3c4d5e6f7g8h9i0j

Options

• --file, --http, --gist

  Forces IntelliShell to treat the LOCATION as a specific type. This is useful if the location string is ambiguous. For example, intelli-shell export --gist 12345 will export to a gist with id 12345 instead of treating it as a file.

• --filter <REGEX>

  Exports only the commands whose command string or description matches the provided regular expression. This is a powerful way to export specific subsets of your library.

  # Export only commands with the #docker or #k8s tag
  intelli-shell export --filter "#(docker|k8s)" > docker_commands.json
  

• -X, --request <METHOD>

  Specifies the HTTP method to use when the LOCATION is an HTTP(S) URL.

  • Default: PUT
  • Allowed values: GET, POST, PUT, PATCH

• -H, --header <KEY: VALUE>

  Adds a custom HTTP header to the request when exporting to an HTTP(S) URL. This can be specified multiple times.

  intelli-shell export --http https://my-api/commands -H "Authorization: Bearer my-token"
  

Examples

• Export all commands to a local file:

  intelli-shell export my_commands.json
  

• Export to a private GitHub Gist:

  Requires a GitHub personal access token with the gist scope. The token can be provided via the GIST_TOKEN environment variable or directly in the configuration file.

  # GIST_TOKEN is set in the environment
  intelli-shell export --gist 1a2b3c4d5e6f7g8h9i0j
  

• Export commands tagged with #gcp to standard output:

  intelli-shell export --filter "#gcp"
  

• Send commands to a custom server using POST:

  intelli-shell export --http https://my-backup-service.com/store -X POST
  

import

The import command is the counterpart to export. It allows you to add commands to your library from an external source, such as a file, an HTTP endpoint, or a GitHub Gist. This is the primary way to restore backups or onboard commands shared by others.

When importing, IntelliShell merges the incoming commands with your existing library. If a command with the string already exists, it is skipped to prevent duplicates.

Usage

intelli-shell import [OPTIONS] [LOCATION]

Arguments

• [LOCATION]

  Specifies the source of the commands to import. This can be a file path, an HTTP(S) URL, or a GitHub Gist ID/URL. If omitted or set to -, IntelliShell reads from standard input (stdin), allowing you to pipe data into it.

  • File: intelli-shell import ./shared_commands.json
  • HTTP: intelli-shell import https://example.com/commands.json
  • Gist: intelli-shell import https://gist.github.com/user/1a2b3c4d5e6f7g8h9i0j
  • Stdin: cat commands.json | intelli-shell import

Options

• --file, --http, --gist

  Forces IntelliShell to treat the LOCATION as a specific type. This is useful if the location string is ambiguous.

• --filter <REGEX>

  Imports only the commands from the source whose command string or description matches the provided regular expression.

  # Import only commands related to 'git' from a shared file
  intelli-shell import --filter "git" team_commands.json
  

• -t, --add-tag <TAG>

  Appends one or more hashtags to the description of every command being imported. This is a convenient way to categorize a new set of commands. This option can be specified multiple times.

  # Import commands from a file and tag them all with #networking and #vpn
  intelli-shell import --add-tag networking --add-tag vpn company_tools.json
  

• --dry-run

  Performs a "trial run" of the import process. The commands from the source are parsed and displayed in the terminal but are not saved to your library. This is useful for inspecting the commands before committing to the import.

• -X, --request <METHOD>

  Specifies the HTTP method to use when the LOCATION is an HTTP(S) URL.

  • Default: GET
  • Allowed values: GET, POST, PUT, PATCH

• -H, --header <KEY: VALUE>

  Adds a custom HTTP header to the request when importing from an HTTP(S) URL. This can be specified multiple times.

  # Import from a private URL that requires authentication
  intelli-shell import --http https://my-api/commands -H "Authorization: Bearer my-token"
  

Examples

• Import commands from a local file:

  intelli-shell import my_commands_backup.json
  

• Import commands from a public GitHub Gist URL:

  intelli-shell import https://gist.github.com/user/1a2b3c4d5e6f7g8h9i0j
  

• Preview commands from a URL before importing:

  intelli-shell import --dry-run https://config.my-company.com/shared-commands
  

tldr Integration

The tldr subcommand provides a powerful way to manage and interact with the community-driven tldr pages. It allows you to populate your command library with practical, real-world examples for thousands of command-line tools.

This integration is designed to give you a head start, so you don't have to build your entire command library from scratch. With a single command, you can import hundreds of useful command templates, complete with variables, ready for you to use.

The tldr functionality is split into two main subcommands:

• fetch: Downloads and imports command examples from the tldr repository.
• clear: Removes previously imported tldr commands from your local library.

These commands provide a simple yet effective way to manage the tldr content within IntelliShell, allowing you to keep your command library relevant and up-to-date.

tldr fetch

The tldr fetch command downloads command examples from the official tldr pages repository and imports them into your IntelliShell library.

This is a great way to quickly populate your library with a vast collection of common and useful commands. The imported commands are stored in a separate tldr category, so they don't mix with your personal bookmarks unless you want them to.

Usage

intelli-shell tldr fetch [OPTIONS] [CATEGORY]

Arguments

• [CATEGORY]: Specifies which tldr category to fetch. If omitted, IntelliShell will automatically fetch the common pages as well as the pages for your current operating system (e.g., linux, osx, or windows).

  For a full list of available categories, you can visit the tldr pages repository.

Options

• -c, --command <COMMAND_NAME>: Fetches examples for one or more specific commands. This option can be repeated to specify multiple commands.

  # Fetch examples for git and docker
  intelli-shell tldr fetch --command git --command docker
  

• -C, --filter-commands [FILE_OR_STDIN]: Fetches examples for commands listed in a file or from standard input. If no path is provided, it reads from stdin. Command names should be separated by newlines.

  # Fetch commands listed in a file named 'my_tools.txt'
  intelli-shell tldr fetch --filter-commands my_tools.txt
  
  # Pipe a list of commands to fetch
  echo -e "tar\nzip" | intelli-shell tldr fetch --filter-commands
  

Examples

• Fetch default pages for your system:

  intelli-shell tldr fetch
  

• Fetch only the common pages:

  intelli-shell tldr fetch common
  

• Fetch pages for a specific tool:

  intelli-shell tldr fetch --command ffmpeg
  

tldr clear

The tldr clear command removes command examples that were previously imported from tldr pages. This allows you to clean up your library or remove categories you no longer need.

This operation only affects tldr commands and will not touch your personal, user-created bookmarks.

Usage

intelli-shell tldr clear [CATEGORY]

Arguments

• [CATEGORY]: Specifies a tldr category to clear from your local library. If this argument is omitted, all tldr commands from all categories will be removed.

  For a list of official categories, see the tldr pages repository.

Examples

• Clear all imported tldr commands: This is useful if you want to start fresh or remove all tldr examples from your search results.

  intelli-shell tldr clear
  

• Clear a specific category: If you've previously fetched pages for a specific platform or category (e.g., osx) and no longer need them, you can remove them individually.

  # Remove only the macOS-specific commands
  intelli-shell tldr clear osx
  

Troubleshooting

This section addresses common issues you might encounter while using IntelliShell. If you can't find a solution here, feel free to open an issue on the GitHub repository.

Hotkey and Integration Problems

If hotkeys like Ctrl+Space or Ctrl+B have no effect, follow these steps:

1. Restart Your Terminal: The installation script modifies your shell's profile (e.g., ~/.bashrc, ~/.zshrc). You must open a new terminal session for these changes to take effect.

2. Verify Shell Profile: Ensure the IntelliShell init is evaluated in your shell's profile file. The installer should add it automatically, but it's good to check.

3. Check for Keybinding Issues: If the steps above are correct, the key combination itself is likely the problem.

   • Conflicts: Another application might be intercepting the keys. For example, some desktop environments use Ctrl+Space to switch keyboard layouts or open a system search.
   • Terminal Limitations: Some terminal emulators do not forward all key combinations to the shell. For instance, Ctrl+Enter (the default "execute" hotkey) is not supported by many terminals.
   • Solution: You can change any conflicting or unsupported hotkey. Set the appropriate environment variable in your shell profile before the IntelliShell line. See the Installation Guide for a full list of integration variables or the Keybindings Configuration for in-app bindings.

Installation and Command Issues

"command not found: intelli-shell"

If your shell cannot find the intelli-shell executable after installation:

1. Restart Your Terminal: Just like with hotkeys, your shell needs to reload its PATH environment variable.

2. Verify PATH: The installer attempts to add the binary's location to your PATH. If this failed, you may need to add it manually to your shell's profile file.

"Permission Denied" errors on Linux/macOS

If you installed manually or are having permission issues, ensure the intelli-shell binary is executable.

# Find the binary and make it executable
chmod +x "$(which intelli-shell)"

General Usage

How do I edit or delete a bookmarked command?

From the search UI (Ctrl+Space), highlight the command you wish to modify.

• Edit: Press Ctrl+U
• Delete: Press Ctrl+D

⚠️ Note: It you can't edit or delete some commands, they might come from the workspace-specific files. You can enable user-only search to exclude them or add them you your own user library before updating the alias or description.

Where is my data stored?

By default, IntelliShell stores its database and configuration in platform-specific user directories. You can override this by setting the data_dir option in your configuration file.

• Configuration File:

  • Linux: ~/.config/intelli-shell/config.toml
  • macOS: ~/Library/Preferences/org.IntelliShell.Intelli-Shell/config.toml
  • Windows: %APPDATA%\IntelliShell\Intelli-Shell\config\config.toml

• Data Files (Database, Logs):

  • Linux: ~/.local/share/intelli-shell
  • macOS: ~/Library/Application Support/org.IntelliShell.Intelli-Shell
  • Windows: %APPDATA%\IntelliShell\Intelli-Shell\data

How can I sync commands between machines?

Use the export and import commands. You can write your library to a file, back it up to a private GitHub Gist, or even serve it from a local HTTP endpoint. See the Syncing and Sharing guide for examples.

Imported commands are not appearing

• Check the Format: Ensure the file you are importing from follows the correct format. Descriptions should be comment lines (#) directly preceding the command. Blank lines can act as separators.

• Use Dry Run: Use the --dry-run flag with the import command to preview how IntelliShell will parse the file without actually saving anything. This helps diagnose formatting issues.

  intelli-shell import --dry-run /path/to/commands.txt
  

Variable suggestions are not synced

The import and export commands are designed to manage commands, their aliases, and descriptions only. They do not sync the history of values you've used for variables.

If you need to back up and restore your entire IntelliShell state, including variable suggestions, you must manually copy the database file (storage.db3) located in your IntelliShell data directory.

Advanced Troubleshooting

Enabling logs

If you encounter a persistent bug, enabling logs can help diagnose the problem. You can do this in two ways:

1. Configuration File: In your config.toml, set enabled = true under the [logs] section. You can also adjust the log level here.

2. Environment Variable: For a quick debug session, set the INTELLI_LOG variable. This overrides the config file. For example: INTELLI_LOG=debug intelli-shell search.

Logs will be written to a file inside the application's data directory.

Resetting to defaults

If your configuration or database becomes corrupted, you can perform a full reset by deleting the application's data and configuration directories listed in the "Where is my data stored?" section above.