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 re-typing long commands with only minor changes, then you've come to the right place.

IntelliShell is a powerful command template and snippet manager that goes far beyond a simple history search to fundamentally improve your command-line experience. It helps you save, find, generate, and fix your most valuable commands directly within your terminal, turning your command line from a simple execution tool into a structured, searchable, and intelligent library.

Why IntelliShell?

IntelliShell is built for users who want to be more efficient and organized in their terminal, with a focus on seamless integration and user experience.

• Seamless Shell Integration: Works directly within your current shell session, making saving and recalling commands feel like a native feature rather than an external tool. Trigger it instantly with a simple keybinding (ctrl+space).

• Smart & Fast Search: Find the command you need in milliseconds. The intelligent search and ranking algorithm lets you find commands even if you only remember a keyword or two.

• Powerful Command Templates: Create reusable command templates using {{variables}}. IntelliShell will prompt you to fill them in on the fly, making any command adaptable to new scenarios.

• Dynamic Completions: Turn static templates into interactive command builders. Power up your templates by defining custom scripts that generate live suggestions for your variables, like listing available git branches or docker containers.

• AI Copilot: Bring the power of AI to your command line. Connect to any local or remote language model to generate complex commands and completions from natural language or instantly fix errors in your last command.

• Fully Customizable: Tailor every aspect to your specific workflow via a simple configuration file—from keybindings and themes to search behavior.

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

• 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 (or virtually any blog post or content with AI enabled).

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. Install the Binary: Place the intelli-shell executable on your machine so you can run it.
2. Configure Shell Integration: Update your shell's profile (e.g., ~/.bashrc, ~/.zshrc) to enable the interactive keybindings (ctrl+space, etc.).

This guide covers the recommended automatic installation and alternative manual methods.

Method 1: Automatic Installation (Recommended)

This is the fastest and easiest way to get started. The installer script automatically detects your OS and architecture, downloads the correct binary, and sets up the shell integration for you.

Note: The installer script will attempt to update all detected shell profiles. If you prefer to handle shell configuration manually, you can set the INTELLI_SKIP_PROFILE=1 environment variable before running the script.

Linux & macOS

Run the following command in your terminal:

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

Windows

Prerequisites:

• The Microsoft Visual C++ Redistributable is required.

• For PowerShell users: You may need to allow script execution first and then run the installer:

  Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
  irm https://raw.githubusercontent.com/lasantosr/intelli-shell/main/install.ps1 | iex
  

• For POSIX-like shell users (Git Bash, WSL, etc.): Same script as for Linux & macOS:

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

Method 2: Manual Installation

These methods are for users who prefer more control or cannot run remote scripts. If you install manually, you must also configure your shell integration to enable the hotkeys (see the "Updating Profile Files" section below).

Option A: From Source

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

LIBSQLITE3_FLAGS="-DSQLITE_ENABLE_MATH_FUNCTIONS" cargo install intelli-shell --locked

Option B: From Pre-compiled Binaries

You can also install pre-built binaries without compiling them from source.

• With cargo-binstall:

  cargo binstall intelli-shell --locked
  

• From GitHub Releases:

  1. Go to the latest release page.
  2. Download the archive (.tar.gz or .zip) for your operating system and architecture.
  3. Extract the intelli-shell executable.
  4. Move it to a directory included in your system's PATH (e.g., /usr/local/bin or ~/.local/bin).

Updating Profile Files

Important: This step is handled automatically by the installer script. You only need to do this if you installed IntelliShell manually (e.g., with Cargo) or if you used the INTELLI_SKIP_PROFILE=1 option with the script.

To enable the interactive hotkeys, you must add a line to your shell's configuration file that sources the IntelliShell initialization script.

Customizing Keybindings

You can override the default keybindings by setting environment variables in your shell's profile file 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_FIX_HOTKEY: Overrides the default ctrl+x hotkey for fixing commands.
• 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, add export INTELLI_SEARCH_HOTKEY=\\C-t to your .bashrc.

Verify Your Installation

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

intelli-shell --version

If the command is found and the hotkeys work, you are ready to go!

Let's move on to Key Concepts.

Key Concepts

Before diving into practical examples, let's cover the core ideas that make this tool a powerful addition to your command-line workflow.

The IntelliShell Philosophy: A Library of Intents

IntelliShell is designed to transform your command-line from a simple execution tool into a structured, intelligent library. It's built around the idea of capturing your intent—the tasks you want to accomplish—and turning them into reusable, interactive "recipes".

This approach helps you work more efficiently by:

• Building a Structured Library: Organize your most-used commands into a searchable knowledge base with descriptions and tags, making them easy to find and understand.

• Streamlining Complex Workflows: Instead of running one command to find an ID and then manually typing it into a second command, IntelliShell lets you build dynamic commands that fetch and use this information in a single, fluid step.

• Reducing Repetitive Typing: Save yourself from re-typing long, complex commands. A short search or alias is all you need to bring up the exact template you're looking for.

• Minimizing Typos: By reusing tested and saved command templates, you significantly reduce the chance of making small, frustrating typos that lead to errors.

Ultimately, IntelliShell helps you focus on what you want to do, rather than the tedious details of how you have to do it.

Your Command-Line Companion

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.

• Search Ctrl+Space: Opens an interactive search UI to find your bookmarked commands
• Bookmark Ctrl+B: Opens a UI to save the command currently on your command line
• Fix Command Ctrl+X: Uses AI to analyze and suggest a fix for a failed command
• Variable Replace Ctrl+L: Opens the variable replacement UI for the command
• Clear Line Esc: A convenience hotkey to clear the entire command line

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

The Building Blocks

IntelliShell's power comes from combining three simple but powerful concepts:

1. Command Templates

The fundamental building block in IntelliShell is the command template. Think of it as a smart snippet or a reusable "recipe" for a command-line task. It represents a generic version of a command that you can adapt to different situations by filling in specific details when you use it.

2. Variables and Suggestions

Templates become truly powerful with variables. Any part of a command enclosed in {{...}} becomes a placeholder. When you select a template, IntelliShell's UI will prompt you to fill in a value for each variable.

Best of all, IntelliShell remembers the values you use. The next time you use the same template, your previous entries will be suggested, saving you from re-typing common inputs.

3. Dynamic Completions

For variables with values that change frequently, you can define dynamic completions. A completion is a shell command that runs in the background to generate a list of suggestions on the fly. This is perfect for things like:

• Listing available Git branches for a git checkout {{branch}} command
• Showing running Docker containers for docker exec -it {{container}} bash
• Fetching Kubernetes services for kubectl logs {{service}}

Now that you understand the core concepts, let's walk through Your First Session.

Your First Session

This chapter will walk you through a complete, hands-on workflow. You'll learn how to bookmark a command, search for it, use variables, and even power it up with dynamic completions. Let's get started!

1. Bookmark Your First Command

The most fundamental workflow in IntelliShell is saving a command you use often. For this tutorial, we'll use a common git command.

• First, type the following command template into your terminal. Don't press enter yet!

  git checkout {{branch}}
  

• With the command still on the line, press Ctrl+B. The bookmarking UI will appear, pre-filling the command you just typed.

• Now, let's add some useful details:

  • Alias: gco (a short, memorable name for quick searching)
  • Description: Checkout a #git branch

• Press Enter to save the bookmark. That's it! You've just saved your first command template.

2. Find and Use Your Command

Now, let's use the command we just saved.

• Clear your terminal and type the alias we just created:

  gco
  

• Now, press Ctrl+Space. Because there's only one command with the alias gco, IntelliShell skips the search screen and takes you directly to the variable replacement UI.

• You'll be prompted to provide a value for the {{branch}} variable. Type in a branch name, for example, feature/new-login, and press Enter.

IntelliShell now places the final, ready-to-run command onto your shell prompt:

git checkout feature/new-login

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

3. Re-run with New Values

IntelliShell includes many small details designed to improve the user experience. One of these is its ability to recognize commands you've already run—even from your shell history—and map them back to their original template.

Imagine you've just run the command above. Now you want to switch to another branch.

• Press the Up Arrow key in your shell to recall the last command: git checkout feature/new-login.
• With the full command on the line, press Ctrl+Space.

IntelliShell is smart enough to recognize that this command was generated from your git checkout {{branch}} template. It will show the original template as the top result. Just press Enter to select it, and you'll be prompted to enter a new value for the {{branch}} variable.

4. Organize with Hashtags

Hashtags are a great way to categorize your commands. Any word in a command's description that starts with a # is treated as a searchable tag. When we created our first bookmark, we added the #git tag. Let's add another command to see how this works.

• Bookmark another command

  Type docker run -it --rm {{image}} into your terminal, press Ctrl+B, and add a description with a hashtag like Run a temporary #docker image.

• Discover and filter by hashtag

  Now that you have commands tagged with #git and #docker, you can use these to filter your search.

  • Clear your command line (Esc) and press Ctrl+Space.
  • All of your bookmarked templates are displayed, type # to filter by a hashtag.
  • The search UI will now suggest all the hashtags you've used. Selecting one will instantly filter your command list to show only the commands with that tag.

💡 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.

5. Your First Completion

Now for the magic. Let's supercharge our git checkout {{branch}} command with dynamic completions. We'll create a completion that automatically suggests all your local git branches.

• Run the following command in your terminal:

  intelli-shell completion new --command git branch "git branch --format='%(refname:short)'"
  

That's it! You've just told IntelliShell that whenever it sees a {{branch}} variable in a git command, it should run git branch --format='%(refname:short)' in the background to fetch suggestions.

Now, try using your gco alias again. Press Ctrl+Space. When the variable replacement UI appears, you'll see a list of all your local git branches, ready for you to select. No more typing branch names by hand!

Now that you've seen how to create and use command templates, let's explore how you can leverage artificial intelligence to generate and fix commands for you in the Introduction to AI.

Introduction to AI

IntelliShell integrates with various AI providers to act as your command-line co-pilot, helping you generate, fix, and even discover commands when you're stuck. This chapter provides a high-level overview of what these features can do and how to get them up and running.

Why Use AI?

AI integration is completely optional, but enabling it unlocks a new level of productivity. Instead of just recalling commands you've already saved, you can create new ones on the fly from natural language descriptions. It's like having an expert assistant who knows the syntax for thousands of tools, ready to help you at a moment's notice.

Features Unlocked by AI

Enabling AI integration powers up several key workflows:

• Generate Commands from Search: Can't find the command you're looking for? In the search UI (Ctrl+Space), type a description of what you want to do (e.g., "find all files larger than 10MB") and press Ctrl+I to let the AI write the command for you.

• Fix Failing Commands: When a command fails, recall it from your history and press Ctrl+X. The AI will analyze the command and the error message to suggest a working version or explain next steps.

• Create New Bookmarks from a Prompt: When bookmarking (Ctrl+B), you can provide a description instead of a command and press Ctrl+I. The AI will generate the command template for you, which you can then edit and save.

• Generate Dynamic Completions: When creating a new completion provide the root command and variable, optionally describing what you need (e.g., "list all running docker containers") on the provider, then press Ctrl+I. The AI will generate the shell command to produce the suggestions.

• Import from Anywhere: The import command gains the ability to parse unstructured text. You can point it at a blog post, a cheat sheet, or even your own shell history, and it will extract and convert commands into reusable templates.

How to Enable AI

AI features are opt-in and disabled by default. To enable them, you need to:

1. Open Your Configuration File

   Run the following command to open your config.toml file in your default editor:

   intelli-shell config
   

2. Enable AI in the Configuration

   Add or modify the [ai] section in the file to set enabled to true:

   [ai]
   enabled = true
   

   Save and close the file.

3. Provide an API Key

   By default, IntelliShell is configured to use Google Gemini, which has a generous free tier. You can obtain an API key from Google AI Studio and set it as an environment variable:

   export GEMINI_API_KEY="your-api-key-here"
   

   You can add this line to your shell's profile file (e.g., ~/.bashrc, ~/.zshrc) to make it permanent.

💡 Note: IntelliShell supports a wide range of AI providers, including OpenAI, Anthropic, and local models via Ollama. For detailed instructions on how to configure different models and customize prompts, see the AI Integration chapter in the reference section.

With AI enabled, you now have even more ways to build your command library. Let's explore how to use them in the next chapter: Populating Your Library.

Populating Your Library

A great command library is a complete one. While you can build your collection over time by bookmarking commands as you work, IntelliShell provides several ways to quickly populate your library from existing sources. This chapter covers the different methods you can use to add commands, from a single bookmark to importing hundreds of examples at once.

Manually

The most direct way to add commands is by creating them yourself. This can be done on the fly as you work or by preparing a file for bulk import.

• One Command at a Time

  The most straightforward method is to bookmark commands as you use them. As you saw in the previous chapter, just type a command in your terminal and press Ctrl+B to save it.

• From a Local File

  For adding multiple commands at once, you can create a plain text file. This is perfect for preparing a set of commands for a new project or for your initial library setup. The file uses a simple format where comments (#) before a command are treated as its description and completions starts with $.

  For example, you could create a file named my_commands.txt:

  # List all running #docker containers
  docker ps
  
  # [alias:dlogs] Tail the logs of a #docker container
  docker logs -f {{container}}
  
  # --- Completions: $ (command) variable: provider
  $ (docker) container: docker ps -a --format '{{.Names}}'
  

  Once your file is ready, you can import all the commands and completions in one go:

  intelli-shell import my_commands.txt
  

  💡 Tip: For more details on the file format and advanced import/export options, see the Syncing and Sharing chapter.

From tldr Pages

If you're getting started or need a quick set of examples for common tools, you can populate your library with commands from the community-driven tldr pages project.

intelli-shell tldr fetch -c tar -c git

This will import useful command templates into a separate tldr space, which you can choose to include or exclude from your searches. Once fetched, they will appear in your search results, giving you instant access to a massive library of commands.

💡 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.

From a Community Gist

You can tap into the collective knowledge of the community by importing command collections from public Gists. This is a great way to share and discover workflows for specific tools.

# Interactively import all commands from a Gist, allowing to discard or edit before importing
intelli-shell import -i https://gist.github.com/lasantosr/137846d029efcc59468ff2c9d2098b4f

# Or non-interactively from a specific file within a Gist
intelli-shell import --gist 137846d029efcc59468ff2c9d2098b4f/docker.sh

💡 Tip: The import command also allows you to filter commands or preview them interactively before importing. For a full list of options, see the import command reference.

From Any Text with AI

If you've enabled AI integration, you can use the import command to extract and convert commands from almost any piece of text—a blog post, a tutorial, or even your own shell history file.

• From Your Shell History

  This is a powerful way to convert your most-used historical commands into a permanent, searchable library. The -i (interactive) flag is highly recommended to curate the results.

  intelli-shell import -i --ai --history bash
  

• From a Website

  Turn any online cheatsheet or tutorial into a source of ready-to-use command templates. The AI will parse the page and extract commands for you to review and import.

  intelli-shell import -i --ai "https://my-favorite-cheatsheet.com"
  

With a well-populated library, you're ready to master IntelliShell's most powerful feature. Let's dive into Using Variables and Completions.

Using Variables and Completions

As we touched on in the Key Concepts chapter, variables are the core of IntelliShell's power, allowing you to turn static commands into reusable templates. This chapter dives deeper into the advanced features of variables and shows you how to supercharge them with dynamic completions.

Advanced Variable Usage

The basic {{variable}} syntax is straightforward, but you can add more intelligence and control to your templates.

Note: While {{...}} is the primary syntax for variables, <...> is also accepted for compatibility when replacing labels or importing commands from other systems.

Secret Variables

Some variables, like comments, API tokens or passwords, shouldn't be saved in your 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 initial suggestions in the UI. This is perfect for commands where the input is one of a few known values.

# 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-friendly branch name from a description. You can automate the formatting:

# Input: "My New Feature" -> Output: "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.

Navigating Between Variables

When filling in variables on the variable replacement TUI, you can navigate between them freely:

• Ctrl+Tab: Move to next variable. After the last variable, cycles back to the first.
• Shift+Tab: Move to previous variable. From the first variable, cycles to the last.
• Enter: Confirm current value and move to next variable. After the last variable, exits and executes / outputs the command if there are no pending variables.

Variables remember their values as you navigate. When you return to a variable you've already filled, its current value will be pre-selected in the suggestions list, making it easy to review or change values before executing the command.

💡 Tip: You can also undo / redo the variable selection with Ctrl+Z / Ctrl+Y.

Dynamic Completions

While providing static options with | is useful, the real power of templates comes from dynamic completions. A completion is a shell command that IntelliShell executes to generate a list of suggestions in real-time.

💡 Important: Completions run asynchronously in the background. When IntelliShell prompts for a variable, it instantly shows suggestions from your history. The dynamic suggestions are merged in as soon as they are ready, so your workflow is never blocked, even by slow network commands.

Global vs. Command-Specific Completions

You can define completions to be either global or tied to a specific command.

• Command-Specific (Recommended): This is the most common use case. The completion only runs when the variable appears in a command starting with a specific root command (e.g., git).

  # This completion runs only for 'git' commands with a {{branch}} variable
  intelli-shell completion new --command git branch "git branch --format='%(refname:short)'"
  

• Global: By omitting the --command flag, you create a global completion that applies to a variable name in any command. This is useful for universally applicable variables.

  # A global completion for {{user}}, useful for commands like `chown {{user}} ...`
  intelli-shell completion new user "awk -F: '\$3 >= 1000 {print \$1}' /etc/passwd"
  

Context-Aware Completions

Completions can adapt their suggestions based on the values of other variables you've already filled in. This is done by using conditional variables inside the completion's command itself. IntelliShell will substitute these variables before execution, making your completions context-aware.

Example: Contextual Kubernetes Pods

Imagine you have a command to view logs for a pod in a specific namespace: kubectl logs -n {{namespace}} {{pod}}. You want the {{pod}} suggestions to be filtered by the {{namespace}} you just selected. You can achieve this with two completions:

1. Namespace Completion: First, create a completion to list all available namespaces.

   intelli-shell completion new --command kubectl namespace "kubectl get ns --no-headers -o custom-columns=':.metadata.name'"
   

2. Context-Aware Pod Completion: Next, create a completion for pods that uses the {{namespace}} variable within its own command.

   intelli-shell completion new --command kubectl pod "kubectl get pods {{-n {{namespace}}}} --no-headers -o custom-columns=':.metadata.name'"
   

Now, when you use the kubectl logs template, IntelliShell first prompts for the namespace. Once you select one, it substitutes that value into the pod completion's command, running kubectl get pods -n <selected-namespace> ... to get a list of pods only from that specific namespace.

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

Workspace Library

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 and completions that are relevant only to your current working environment.

How It Works

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

This location can be either a single file or a directory:

• If it's a file: The file is loaded, and its commands are automatically tagged with the name of the parent directory.
• If it's a directory: All files inside the directory (and its subdirectories) are loaded recursively. Each command is tagged with the name of the file it came from (excluding the extension). Hidden files are skipped.

All found files 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.

Advanced Use Cases: User and System-Level Files

The primary and most common use case for this feature is the local workspace file described above. This is the recommended approach for sharing project-specific commands with your team.

However, to support non-personal scenarios, like managing multiple machines in a network with shared folders, IntelliShell also loads .intellishell files from user-level and system-wide locations. This allows you to define a common set of commands once and have them automatically available across many systems without needing to manually import them on each one.

• User-Level: ~/.intellishell
• System-Wide: /etc/.intellishell (Unix) or C:\ProgramData\.intellishell (Windows)

When to Use a Workspace Library

Workspace libraries are ideal for commands that are tied to a specific project. Here are the key benefits:

• Workspace-Aware: Commands and completions are only available when you are working inside that workspace's directory tree.
• Session-Only: Workspace items are not saved to your permanent database, keeping your personal library clean.
• Top Priority: Workspace-specific commands always appear at the top of your search results.
• Version Controllable: You can commit .intellishell to your Git repository to share common workspace commands with your entire team.
• Team Onboarding: New team members can instantly access common build, test, and deployment commands.
• Discoverability: Make project-specific scripts and tools easily discoverable—just hit Ctrl+Space to see what's available.

For your own personal commands that you use everywhere, it is still best to import them into your permanent library. This allows you to benefit from features like variable suggestion history and usage-based ranking, which do not apply to temporary workspace commands.

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. You can check IntelliShell's own file for a real-world example.

Here is a sample .intellishell file for a Terraform project:

#!intelli-shell

# Format all Terraform files in the project
terraform fmt -recursive

# [alias:tfp] Plan infrastructure changes for a specific environment
terraform plan -var-file="envs/{{env}}.tfvars"

# [alias:tfa] Apply infrastructure changes for a specific environment
terraform apply -var-file="envs/{{env}}.tfvars"

# Show the state for a specific resource
terraform state show '{{resource}}'

## -- Completions --
$ (terraform) env: find envs -type f -name "*.tfvars" -printf "%P\n" | sort | sed 's/\.tfvars$//'
$ (terraform) resource: terraform state list

💡 Tip: For more details on the file format and its syntax, see the File Format section of the Syncing and Sharing chapter.

With your personal and workspace libraries set up, let's look at how to back up, restore, and share your personal commands in Syncing and Sharing.

Syncing and Sharing

IntelliShell makes it easy to back up your 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 and completions 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.

File Format

IntelliShell uses a simple, human-readable text format that makes it easy to view and edit your commands manually. The parser is designed to be flexible, allowing it to understand not only its official format but also variations found in sources like tldr pages or other shell script files.

A command is any line that isn't a blank line or a comment. To add a description, simply place one or more comment lines directly above the command (comment lines can start with # or //). For better organization, you can also include an alias within the description by adding [alias:your-alias] at the beginning or end of the comment block.

If you have a long command, you can split it across multiple lines by ending each line (except the last) with a backslash (\).

Dynamic completions are also supported. Any line starting with a dollar sign ($) is treated as a completion definition. Use the format $ (command) variable: provider for command-specific completions, or $ variable: provider for global ones.

# --------------------------------------------------------------
#   Commands
# --------------------------------------------------------------

# A multi-line description for a command
# with a #hashtag for organization.
git log --oneline --graph --decorate

# [alias:tfp] Plan infrastructure changes for a specific environment.
# This command is multi-line for readability.
terraform plan \
    -var-file="envs/{{env}}.tfvars"

# --------------------------------------------------------------
#   Completions
# --------------------------------------------------------------

# A global completion for any `{{branch}}` variable.
$ branch: git branch --format='%(refname:short)'

# A command-specific completion for the `{{env}}` variable when using `terraform`.
$ (terraform) env: find envs -type f -name "*.tfvars" -printf "%P\n" | sort | sed 's/\.tfvars$//'

Local Backup & Restore

The simplest way to back up your library 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.

# Back up to a file
intelli-shell export my_commands.bak

# Restore from the file
intelli-shell import my_commands.bak

Syncing with a GitHub Gist

Using a GitHub Gist is a flexible way to manage your 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.

Before you can export to a Gist for the first time, you must create it on GitHub to get its unique ID.

# The --gist flag is required when the location could be mistaken for a file name
intelli-shell export --gist 137846d029efcc59468ff2c9d2098b4f/command.sh

# Or use the URL
intelli-shell import https://gist.github.com/lasantosr/137846d029efcc59468ff2c9d2098b4f

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.

Supported Gist Locations

IntelliShell is flexible and can understand various Gist location formats.

Full URLs

You can use almost any URL related to your Gist, including the main Gist page, the raw content URL, or the API endpoint.

Shorthand Formats

For convenience, you can also use shorter formats (these require --gist flag to disambiguate):

• {id}: Just the unique ID of the Gist
• {id}/{file}: Target a specific file within the Gist
• {id}/{sha}: Target a specific version (commit SHA) of the Gist
• {id}/{sha}/{file}: Target a specific file at a specific version

💡 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 storage, you can configure IntelliShell to sync with any custom HTTP endpoint. This is ideal for teams who want to maintain a private, centralized library on their own infrastructure.

When exporting, IntelliShell sends a PUT request with a JSON payload of your commands and completions. 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

Fine-Tuning Your Workflow

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

Interactive Review

For more control over what gets imported or exported, you can use the --interactive (-i) flag. This opens a terminal UI that displays a list of all commands and completions before the action is performed.

In this interactive view, you can:

• Review every command and completion
• Edit a completion, command or its description on the fly
• Discard/Undiscard specific commands or completions by pressing Space

This is especially useful when importing from a new or untrusted source, or when using the AI parser, as it gives you a final chance to clean up and validate the results.

# Interactively review the content from a file before importing
intelli-shell import -i --gist {{gist-url}}

# Interactively choose which docker commands and completions to export
intelli-shell export -i --filter docker

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 --filter "^docker" docker_commands.sh

⚠️ Note: When exporting filtered commands, only those completions that apply to those filtered commands are exported.

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 path/to/commands.file

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 and completions 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

For Teams & Organizations

IntelliShell is more than just a personal productivity tool—it's a powerful asset for engineering teams.

By standardizing common tasks and making project-specific knowledge easily accessible, it streamlines collaboration, accelerates onboarding, and creates a more efficient development environment for everyone.

Standardize Workflows within Workspaces

Consistency is key in a team environment. The workspace library feature ensures that every developer is using the same tools in the same way.

• Version-Controlled Scripts: By committing the .intellishell file to your repository, you version-control your project's common tasks. When a build command changes, you update it in one place, and everyone gets the update automatically on their next git pull.

• Dev Container Integration: For teams using Dev Containers or other standardized development environments, IntelliShell is a perfect fit. You can configure your devcontainer.json to automatically install it, providing a seamless, out-of-the-box experience where every developer has immediate access to the project's command library.

💡 The IntelliShell project itself uses a .intellishell file to manage common development tasks like running tapes or creating a new release.

Centralize and Share Knowledge

Beyond a single repository, IntelliShell provides tools to create a centralized knowledge base for your technical department.

You can set up shared Gists, files, or HTTP endpoints to serve command templates for the common tools used within the department, such as Kubernetes, Terraform, or internal CLIs.

Developers can then use the import command to pull these shared templates into their local IntelliShell library, ensuring everyone has access to the same set of approved, up-to-date commands.

This approach turns scattered information from wikis and tutorials into a structured, searchable, and shared resource, right in the command line.

Accelerate Onboarding

Getting new developers up to speed is a common challenge. They need to learn a project's unique setup, build commands, and deployment scripts. IntelliShell makes this process nearly effortless by leveraging both workspace-aware file and centralized knowledge.

• Instant Command Discovery: With a .intellishell file in the repository, a new developer can open a terminal, press ctrl+space, and immediately see all the essential project commands. There's no need to hunt through README files or ask teammates for help.

• Executable Documentation: The combination of workspace commands and the ability to import shared templates acts as living, executable documentation. It doesn't just describe how to build the project; it provides the exact, ready-to-run commands, complete with descriptions and placeholders for arguments.

Increase Team Productivity

By addressing the small, everyday frictions of command-line work, IntelliShell adds up to significant productivity gains for the whole team.

• Reduced Cognitive Load: Developers no longer need to memorize complex commands or switch contexts to find the information they need. This allows them to stay focused on writing code.

• Fewer Errors: With command templates and dynamic completions, there's less room for typos or incorrect flag usage.

• AI-Powered Assistance: For technical departments that use AI, developers can configure IntelliShell with their own API keys. This unlocks features like natural language command generation and automatic error fixing, further reducing friction and accelerating tasks.

• Empowered Collaboration: When everyone has easy access to the same set of tools and commands, it fosters a more collaborative and efficient engineering culture.

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: ~/.config/intelli-shell/config.toml
• macOS: ~/Library/Application Support/org.IntelliShell.Intelli-Shell/config.toml
• Windows: %APPDATA%\IntelliShell\Intelli-Shell\config\config.toml

💡 Tip: You can quickly open this file for editing by running intelli-shell config, or find its location with intelli-shell config --path.

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

• AI Integration: Learn how to connect IntelliShell to AI providers like OpenAI or local Ollama models. This chapter covers setting up API keys, choosing models, and customizing prompts to power features like command generation and error fixing.

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, 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
• exec_on_alias_match: If set to true, an exact alias match will execute the command immediately, rather than populating the input line for you to run manually

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
# Whether to directly execute the command if it matches an alias exactly, instead of just selecting
exec_on_alias_match = 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"]
# Prompt ai about suggestions (e.g. when searching for commands)
ai = ["ctrl-i", "ctrl-x"]
# 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"
# Move to the next variable when replacing variables
variable_next = "ctrl-tab"
# Move to the previous variable when replacing variables
variable_prev = ["shift-tab", "shift-backtab"]

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.

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 = "darkgrey"
# 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 = "default"
# 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.

Arcade

A playful variation on the default theme, bringing a vibrant and retro feel to your terminal.

[theme]
primary = "default"
secondary = "dim"
accent = "136"
comment = "rgb(106, 153, 66)"
error = "dark red"
highlight = "none"
highlight_symbol = "» "
highlight_primary = "220"
highlight_secondary = "222"
highlight_accent = "208"
highlight_comment = "rgb(143, 221, 75)"

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"

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 three sources:
# 1. Completion Score: The value is present on the dynamic completions for the variable
# 2. Context Score: Other variable values already selected to the command
# 3. 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 being present on dynamic variable completions
completion.points = 200

# 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

Now that you have the search ranking system fine-tuned to your workflow, you can enhance your productivity even further by leveraging artificial intelligence. Let's explore how to set up AI Integration.

AI Integration

IntelliShell integrates with various AI providers to provide powerful features like generating commands from natural language, automatically fixing errors in failed commands, and importing new commands from text sources. This chapter guides you through configuring these features.

Enabling AI Features

AI integration is disabled by default. To turn on all AI-powered functionality, you must first enable it:

[ai]
# A global switch to enable or disable all AI-powered functionality
enabled = false

📝 Note: By default, IntelliShell is configured to use Google Gemini, given that it has a generous free tier. For the AI features to work out-of-the-box, you must set the GEMINI_API_KEY environment variable with a valid key from Google AI Studio.

Alternatively, you can configure a different provider (like OpenAI or a local Ollama model) by following the examples in the sections below.

Configuration Overview

The [ai] section in your configuration is organized into three main parts, which work together to connect IntelliShell to your preferred AI provider:

1. Task Assignment: This is where you assign a specific AI model to a task , such as suggesting commands or fixing errors.
2. Model Catalog: This is a library of all the AI models you want to make available. Each model is given a unique alias (e.g., "gemini", "gpt4-fast") that you can then use in the Task Assignment section.
3. Custom Prompts: For advanced control, this section allows you to customize the instructions that IntelliShell sends to the AI provider for each task.

Let's look at each part in detail.

1. Task Assignment

In the [ai.models] section, you tell IntelliShell which model from your catalog to use for each specific AI-powered task.

# Assign models to tasks by their alias (which must be defined in the Model Catalog below)
[ai.models]
# The alias of the model to use for generating command templates from natural language
suggest = "main"
# The alias of the model used to fix or explain a failing command
fix = "main"
# The alias of the model to use when importing commands
import = "main"
# The alias of the model to use when generating a command for a dynamic variable completion
completion = "main"
# The alias of a model to use as a fallback if the primary model fails due to rate limits
fallback = "fallback"

2. Model Catalog

The [ai.catalog] section is where you define the connection details for every model alias you wish to use. This allows you to configure multiple models from different providers and easily switch between them in the Task Assignment section.

[ai.catalog.main]
provider = "gemini"
model = "gemini-flash-latest"

[ai.catalog.fallback]
provider = "gemini"
model = "gemini-flash-lite-latest"

Supported Providers

IntelliShell has native support for several major providers. It will automatically look for API keys in the standard environment variables associated with each one:

Configuration Examples

Below are several examples for configuring different models within your [ai.catalog].

💡 Shortcut: You can also just overwrite the default main and fallback aliases directly in your catalog. This changes the model used without needing to edit [ai.models].

• OpenAI

  To use a model from OpenAI, like GPT-4o:

  [ai.catalog.gpt-4o]
  provider = "openai"
  model = "gpt-4o"
  

• Anthropic Claude

  To use a model from Anthropic, like Claude 4.0 Sonnet:

  [ai.catalog.claude-sonnet]
  provider = "anthropic"
  model = "claude-sonnet-4-0"
  

• Local Models with Ollama

  You can run models locally using Ollama. This is a great option for privacy and offline use.

  [ai.catalog.local-llama]
  provider = "ollama"
  model = "llama3"
  # If Ollama is running on a different host, specify the URL:
  # url = "http://192.168.1.100:11434"
  

• Using OpenAI-Compatible Endpoints

  Many other AI providers (like Groq, xAI, DeepSeek, etc.) offer APIs that are compatible with OpenAI's API structure. You can connect to these providers by setting the provider to openai.

  • Groq

    Groq is known for its high-speed inference. To use a Llama 3 model via Groq:

    [ai.catalog.groq-llama]
    provider = "openai"
    model = "llama-3.1-8b-instant"
    url = "https://api.groq.com/openai/v1"
    api_key_env = "GROQ_API_KEY"
    

  • xAI

    To connect to a model from xAI:

    [ai.model.grok]
    provider = "openai"
    model = "grok-4"
    url = "https://api.x.ai/v1"
    api_key_env = "XAI_API_KEY"
    

  • DeepSeek

    To use a model from DeepSeek:

    [ai.model.deepseek]
    provider = "openai"
    model = "deepseek-chat"
    url = "https://api.deepseek.com"
    api_key_env = "DEEPSEEK_API_KEY"
    

  • Azure OpenAI Service

    To connect to a model you've deployed on Azure:

    [ai.catalog.azure-gpt4]
    provider = "openai"
    model = "my-gpt4-deployment"
    url = "https://your-resource-name.openai.azure.com/"
    api_key_env = "AZURE_OPENAI_KEY"
    

3. Customizing Prompts

For advanced users, IntelliShell allows you to completely customize the system prompts sent to the AI for the suggest, fix, import and completion tasks. This gives you fine-grained control over the AI's behavior, tone, and output format.

The prompts are defined in the [ai.prompts] section.

Dynamic Placeholders

When crafting your prompts, you can use special placeholders that IntelliShell will replace with real-time contextual information before sending the request to the AI:

• ##OS_SHELL_INFO##: Replaced with details about the current operating system and shell
• ##WORKING_DIR##: Replaced with the current working directory path and a tree-like view of its contents
• ##SHELL_HISTORY##: Replaced with the last few commands from the shell's history, this is only available for the fix prompt

You can view the well-tuned default prompts in the default_config.toml file to use as a starting point for your own customizations.

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 [SUBCOMMAND] [OPTIONS] [ARGS]

💡 Tip: Every subcommand supports the -h flag for a summarized view of its options and --help for a more detailed explanation, including examples.

Commands

Here is a summary of all available commands, with each one detailed on its own page.

Global Flags for Interactive Mode

Several commands can be run either non-interactively or through an interactive TUI by using the -i or --interactive flag. When in interactive mode, you can also 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

config

The config command opens the intelli-shell configuration file in your default editor, or displays the path to it.

Usage

intelli-shell config [OPTIONS]

Options

• -p, --path

  Displays the path to the configuration file instead of opening it.

Examples

Open the configuration file

This will launch the default editor to modify your config.toml.

intelli-shell config

Show the path to the configuration file

This is useful for scripting or for finding where your configuration is located.

intelli-shell config --path

logs

The logs command displays the logs from the last execution of intelli-shell, if they were enabled.

Usage

intelli-shell logs [OPTIONS]

Options

• -p, --path

  Displays the path to the log file instead of the logs content.

Examples

Show the logs from the last execution

intelli-shell logs

Show the path to the log file

intelli-shell logs --path

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.

💡 Tip: Can't remember the exact command details? While in the interactive TUI, you can press Ctrl+I or Ctrl+X with a natural language description to prompt AI for a command.

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.

• --ai

  Uses AI to generate a command and its description from the COMMAND_STRING prompt. This is most effective when paired with -i to review the AI's suggestions before saving.

• -i, --interactive

  Opens the interactive TUI to bookmark the command, pre-filling any details provided via other arguments and options.

• -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

Bookmark a Simple Command

Quickly save a command without any extra details. The command string is wrapped in single quotes to prevent the shell from interpreting special characters.

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

Add a Command with Full Details

For a more useful bookmark, provide an alias (-a) for quick searching and a description (-d) with hashtags for organization.

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

Pre-fill the Interactive UI

Use this when you have a command ready but want to use the TUI to add the alias and description. It's a middle ground between fully manual and fully interactive bookmarking.

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

Generate a Command with AI

This is the most powerful workflow for creating new commands. Provide a description of what you want to do, and the AI will generate the command and its details for you. The -i flag is highly recommended here to review and edit the suggestions before saving.

intelli-shell new -i --ai 'undo last n commits'

search

The search command finds stored commands based on a query and can also use AI to generate new ones on the fly.

By default, this command performs a non-interactive search and prints matching commands to standard output. To open the interactive search TUI (the behavior of the Ctrl+Space hotkey), you must use the -i or --interactive flag.

💡 Tip: Can't find what you're looking for? While in the interactive TUI, you can press Ctrl+I or Ctrl+X with a natural language query to prompt AI for commands.

Usage

intelli-shell search [OPTIONS] [QUERY]

Arguments

• QUERY The search query used to filter commands.

  • When used with the --ai flag, this string is treated as a natural language prompt for the AI to generate a command.

Options

• -m, --mode <MODE>

  Specifies the search algorithm to use. See the "Advanced Search Syntax" section below for details on 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

  Excludes commands imported from tldr pages from the search results.

• --ai

  Uses AI to generate commands based on the QUERY prompt instead of searching your local library. This is most effective in interactive mode (-i).

• -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

Open the Interactive Search

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

intelli-shell search --interactive

Perform a Non-Interactive Search

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

intelli-shell search docker

Non-Interactive Search with Options

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

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

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

Use AI to Suggest Commands

To use AI to suggest commands based on a natural language prompt:

intelli-shell search -i --ai 'undo last n commits'

This will open the interactive interface with AI-suggested commands, which you can then review and select.

💡 Tip: Saving AI-Generated Commands

Commands generated using --ai in the search interface are for one-time use and are not saved to your library automatically.

To save a generated command for future use, you can place it on your terminal line from the search results and then use either the Ctrl+B hotkey or the new command to bookmark it.

replace

The replace command populates variables within a command string. Its primary function is to take a command template containing placeholders 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.

Variable Syntax

IntelliShell primarily uses the {{variable-name}} format for placeholders, but it also support the <variable_name> format for compatibility with other tools or examples.

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 populates any remaining variables from their corresponding environment variables (e.g., {{api-key}} maps to API_KEY). This gives access to all environment variables without listing them explicitly. This is always enabled in interactive mode.

• -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

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!"

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"

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

Launching the Interactive UI

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

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

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

fix

The fix command provides a non-interactive way to correct a failing command using AI. It's the command-line equivalent of the Ctrl+X hotkey, designed for use in scripts or automated workflows.

It acts as an intelligent wrapper that executes a command and, if it fails, uses AI to diagnose the problem and suggest a solution.

All diagnostic messages are printed to stderr, while the corrected command (if any) is printed to stdout, allowing it to be used programmatically.

How It Works

Tt first executes the command. If the command fails (i.e., exits with a non-zero status code), fix captures the output and sends it, along with some context, to the configured AI for analysis.

The AI's diagnosis is printed to stderr, while the clean, corrected command (if one is found) is printed to stdout. This separation allows you to easily pipe the corrected command to another process or variable.

⚠️ Important

The fix command is intended for non-interactive shell commands (e.g., ls, git, docker). Executing interactive applications like vim or less through it may lead to unexpected behavior.

Usage

intelli-shell fix <COMMAND>

Arguments

• <COMMAND>: The full command string to execute and potentially fix.

Example

Here is what happens when you run a command with a common typo through intelli-shell fix.

Command:

intelli-shell fix "git comit amend"

Output:

> git comit amend
git: 'comit' is not a git command. See 'git --help'.

The most similar command is
        commit

────────────────────────────────────────────────────────────────────────────────

🧠 IntelliShell Diagnosis

❌ Git Command Typo
The command "git comit amend" failed because "comit" is a misspelling of the 
"commit" subcommand. Git recognized "comit" as an unrecognized command and 
suggested "commit" as the most similar valid command. This error often occurs 
due to a simple typographical mistake.

✨ Fix
To fix this, correct the spelling of "comit" to "commit". The "--amend" flag 
is commonly used with "git commit" to modify the most recent commit.

Suggested Command 👉
git commit --amend

In this example, all the informational text is sent to stderr.

Only the final, corrected command is sent to stdout, making it safe to use in scripts like fixed_cmd=$(intelli-shell fix "git comit amend").

export

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

By default, commands and completions are exported in a simple, human-readable text format.

📝 Note: This command only exports your personal, bookmarked commands and completions. Examples fetched from tldr pages or workspace-specific items 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.

Options

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

  Forces IntelliShell to treat the LOCATION as a specific type. This is useful if the location string is ambiguous (e.g., 12345), to distinguish between a local file and a Gist ID.

• --filter <REGEX>

  Exports only the commands whose content or description matches the provided regular expression.

  When commands are filtered, only completions for variables present on those commands are exported.

• -X, --request <METHOD>

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

• -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.

• -i, --interactive

  Opens an interactive TUI to review, edit, and select specific commands before exporting. In this interface, you can update commands before exporting and use Space / Ctrl+Space to discard or include highlighted / all commands.

Examples

Export All Commands to a File

This is the simplest way to create a local backup of your library.

intelli-shell export my_commands.bak

Export to a Private GitHub Gist

To sync your library across machines, you can export to a Gist. This requires a GitHub Personal Access Token with the gist scope, provided via the GIST_TOKEN environment variable or in your config file.

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

Export a Subset of Commands

Use --filter to export only the commands you need. This example exports commands tagged with #gcp (and any completion applicable to those commands) to standard output.

intelli-shell export --filter "#gcp"

Send to a Custom Server

You can integrate IntelliShell with your own infrastructure by exporting to a custom HTTP endpoint.

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

Interactively Select Commands to Export

For fine-grained control, use interactive mode. This example finds all commands related to "docker" and then opens a TUI where you can hand-pick which ones to save to the file.

intelli-shell export -i --filter "docker" docker_commands.bak

import

The import command is the counterpart to export. It allows you to add commands and completions 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 and completions with your existing library. If a command with the exact same command string or a completion for the same variable 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.

Options

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

  Forces IntelliShell to treat the LOCATION as a specific type, which is useful if the location string is ambiguous (e.g., a numeric Gist ID).

• --filter <REGEX>

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

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

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

• --dry-run

  Performs a "trial run" of the import. Commands are parsed and displayed but are not saved to your library, which is useful for inspecting a source before committing.

• --ai

  Uses AI to parse and extract command templates from unstructured text sources like web pages or shell history.

• --history <SHELL>

  Imports shell history (bash, zsh, fish, nushell, powershell or atuin). This option requires the --ai flag.

• -i, --interactive

  Opens an interactive TUI to review, edit, and select commands before importing. You can use Space / Ctrl+Space to discard or include highlighted / all commands.

• -X, --request <METHOD>

  Specifies the HTTP method to use for an HTTP(S) LOCATION (default: GET).

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

  Adds a custom HTTP header to the request for an HTTP(S) LOCATION. This can be specified multiple times.

Examples

Import from a Local File

Restore your library from a local backup file.

intelli-shell import my_commands.bak

Import from a Public Gist

Onboard a set of shared commands and completions from a teammate or the community.

intelli-shell import https://gist.github.com/lasantosr/137846d029efcc59468ff2c9d2098b4f

Preview Before Importing

Use --dry-run to safely inspect the contents of a remote file without modifying your library.

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

Convert Shell History into Bookmarks with AI

This is a powerful way to convert your most-used historical commands into a permanent, searchable library. The -i flag is highly recommended to curate the results.

intelli-shell import -i --ai --history bash

Extract Commands from a Web Page with AI

Turn any online cheatsheet or tutorial into a source of ready-to-use command templates. The AI will parse the page and extract commands for you to review and import.

intelli-shell import -i --ai https://www.example.com/cheatsheet

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. It acts as a powerful form of command discovery; when you're unsure how to use a tool like tar or ffmpeg, the imported tldr examples provide a set of ready-to-use templates directly in your search results.

Available Subcommands

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 with community-driven examples.

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 examples are stored in a separate tldr category so they don't mix with your personal bookmarks. Once fetched, they will appear in your search results, giving you instant access to a massive library of commands.

💡 Tip: You can re-run this command at any time to update your local copy of the tldr pages to the latest version.

Usage

intelli-shell tldr fetch [OPTIONS] [CATEGORY]

Arguments

• CATEGORY Specifies which tldr category (a collection of pages) to fetch.

  If omitted, IntelliShell automatically fetches 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, regardless of platform. This option can be repeated to specify multiple commands.

• -C, --filter-commands [FILE_OR_STDIN]

  Fetches examples only 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.

Examples

Fetch Default Pages for Your System

Running the command without arguments is the easiest way to get started. It fetches the most relevant pages for your environment.

intelli-shell tldr fetch

Fetch a Specific Platform

If you only want pages from a specific platform, like common, you can specify it as an argument.

intelli-shell tldr fetch common

Fetch Pages for Specific Tools

If you only need examples for a particular command, use the --command flag.

intelli-shell tldr fetch --command git --command docker

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 (e.g., linux, osx, common) to clear from your 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 fetched pages for a specific 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

Variable Completions

The completion subcommand is used to manage dynamic variable completions.

This feature allows you to define a shell command that, when executed, provides a list of possible values for a given variable. This is particularly useful for variables that have a dynamic set of possible values, such as container names, git branches, or available network interfaces.

Available Subcommands

The completion functionality is split into three main subcommands:

• new: Adds a new dynamic completion for a variable
• list: Lists all configured dynamic variable completions
• delete: Deletes an existing dynamic variable completion

completion new

The new subcommand adds a new dynamic completion for a variable. This allows you to specify a shell command that will be executed to generate a list of possible values for a variable.

💡 Tip: Can't figure out the exact command details? While in the interactive TUI, you can press Ctrl+I or Ctrl+X with a natural language description on the provider field to prompt AI for a command.

Usage

intelli-shell completion new [OPTIONS] [VARIABLE] [PROVIDER]

Arguments

• VARIABLE The name of the variable to provide completions for.

  This argument is mandatory unless you are running in interactive mode (-i).

• PROVIDER The shell command that generates the suggestion values when executed. The command should output a list of values separated by newlines.

  This argument is mandatory unless you are running in interactive mode (-i) or have enabled ai mode (--ai).

  ⚠️ 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

• -c, --command <COMMAND>

  The root command where this completion must be triggered. If not provided, the completion will be global and will be triggered for any command that uses the specified variable.

• --ai

  Uses AI to suggest the completion command. This is most effective when paired with -i to review the AI's suggestions before saving.

• -i, --interactive

  Opens the interactive TUI to add a new dynamic completion.

• -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

Add a new completion for a global variable

This will provide suggestions for any {{remote}} variable, regardless of the command it's used in.

intelli-shell completion new remote "git remote"

Add a new completion for a command-specific variable

This will provide suggestions for the {{branch}} variable only when it's used in a git command.

intelli-shell completion new --command git branch "git branch --format='%(refname:short)'"

Use AI to suggest a completion for a variable

This will open the interactive UI and use AI to suggest a command that can provide completions for the container variable.

intelli-shell completion new -i --ai container

completion list

The list subcommand displays all configured dynamic variable completions, allowing you to see what completions are available and how they are configured.

Usage

intelli-shell completion list [OPTIONS] [COMMAND]

Arguments

• COMMAND If provided, the list will be filtered to show only completions for that command.

Options

• -i, --interactive

  Opens an interactive list of variable completions.

• -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

List all variable completions

This will list all completions, both global and command-specific, in a non-interactive format.

intelli-shell completion list

List variable completions for a specific command

This will list only the completions that are configured for the git command.

intelli-shell completion list git

Open the interactive list of completions

This will open an interactive TUI to browse, edit, and delete completions, while previewing their suggestions.

intelli-shell completion list -i

completion delete

The delete subcommand removes an existing dynamic variable completion.

Usage

intelli-shell completion delete [OPTIONS] <VARIABLE>

Arguments

• <VARIABLE> The variable name of the completion to delete.

Options

• -c, --command <COMMAND>

  The root command of the completion to delete. If not provided, it will delete the global completion for the specified variable.

Examples

Delete a global dynamic completion

This will delete the completion for the container variable that applies to all commands.

intelli-shell completion delete container

Delete a command-specific dynamic completion

This will delete the completion for the branch variable that is specific to git commands.

intelli-shell completion delete --command git branch

update

The update command checks for a new version of IntelliShell and, if one is available, attempts to automatically update the application.

This command provides a convenient way to stay on the latest version without needing to re-run the installation script manually.

Usage

intelli-shell update

How It Works

The update process depends on how you initially installed IntelliShell:

• Installed via Official Script: If you installed IntelliShell using the recommended install.sh or install.ps1 script, the update command will download the latest release and replace your current executable with the new version.

• Other Installation Methods: If you installed IntelliShell using cargo install, by building from source, or through other manual methods, the automatic update will not be performed. Instead, the command will check for the latest version and provide you with instructions on how to update it using the same method you used for the initial installation.

Examples

Check for and apply updates

Simply run the command without any arguments. IntelliShell will handle the rest.

intelli-shell update

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 init 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 or F2
• Delete: Press Ctrl+D

⚠️ Note: If you can't edit or delete some commands, they might come from the workspace-specific .intellishell files. You can enable user-only search to exclude them or add them to 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.

• Configuration File:

  • Linux: ~/.config/intelli-shell/config.toml
  • macOS: ~/Library/Application Support/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

💡 Tip: You can quickly find the location of your configuration and log files by running:

# Show path to config.toml
intelli-shell config --path

# Show path to intelli-shell.log
intelli-shell logs --path

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.

Viewing Logs

Once logging is enabled, you can easily view the logs from the last run using the logs command:

# Display the full log content
intelli-shell logs

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.