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 smart command-line assistant designed to solve these exact problems. 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.

Key Features

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

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

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

• Smart Completions: Power up your templates by defining custom scripts that generate live suggestions for your variables, like listing available git branches or docker containers.

• AI-Powered Assistance: Generate complex commands from natural language, instantly fix errors in your last command, and import templates from any text source—all powered by your favorite language models.

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

• Workspace-Aware: Automatically load workspace-specific commands and completions from a .intellishell file in your current folder or workspace.

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

• Extensible Knowledge: Instantly boost your library by fetching and importing command examples from the community-driven tldr pages (or virtually any blog post or content with AI enabled).

How to Use This Book

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

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

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

• Configuration: This section is your reference for personalizing IntelliShell.

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

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

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

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

Installation

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

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

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

Method 1: Installer Script

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

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

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

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

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

Windows (PowerShell)

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

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

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

Method 2: Building from Source

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

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

To enable hotkeys integration, additional steps are required:

Customizing Shell Integration

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

• INTELLI_SEARCH_HOTKEY: Overrides the default ctrl+space hotkey for searching commands.
• INTELLI_BOOKMARK_HOTKEY: Overrides the default ctrl+b hotkey to bookmark a command.
• INTELLI_VARIABLE_HOTKEY: Overrides the default ctrl+l hotkey for replacing variables.
• INTELLI_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, you would add the line export INTELLI_SEARCH_HOTKEY=\\C-t to your .bashrc.

Verify Your Installation

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

intelli-shell --version

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

Basic Usage

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

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

Core Hotkeys

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

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

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

• Fix Command Ctrl+X: When a command fails, press the up arrow to recall it, then use this key to let AI analyze the command and the error message to suggest a working version.

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

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

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

Additionally, all keybindings used within the interactive UIs mentioned on the book are customizable in your configuration file, you can update them on the Key Bindings chapter.

Your First Bookmark

Let's walk through the fundamental workflow: saving a command, searching for it, and running it again with new values.

1. Write a command

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

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

2. Bookmark it

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

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

   Press Enter to save the bookmark.

3. Search for it

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

   • Type ubuntu:latest and press Enter.

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

   docker run -it --rm ubuntu:latest
   

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

4. Re-run with new values

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

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

Organize with Hashtags

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

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

1. Bookmark another command

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

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

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

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

AI-Powered Workflows

Beyond managing bookmarks, IntelliShell's can act as your command-line co-pilot, helping you fix errors and generate new commands when you're stuck.

Fix a Failing Command

We've all been there: you type a long command, only for it to fail due to a small typo. Instead of manually debugging, let the AI handle it.

1. Run a command that fails

   Let's try to list files with a mistyped flag:

   ls --long
   

   Your shell will return an error: ls: unrecognized option '--long'.

2. Recall and Fix

   • Press the Up Arrow key in your shell to bring back the failing command
   • With ls --long on the line, press Ctrl+X

   The AI will analyze both the command and the error it produced. It will suggest the corrected command (ls -l or ls --format=long), placing it directly on your prompt.

Generate a Command from a Description

Can't remember the exact syntax for find or ffmpeg? Just describe what you want to do.

1. Open the search UI

   Press Ctrl+Space to open the IntelliShell search prompt.

2. Describe the task

   Instead of searching for a bookmark, type a description of the command you need. For example: find all files larger than 10MB in the current folder

3. Generate with AI

   With your description in the search box, press Ctrl+I. The AI will generate the corresponding shell command (e.g., find . -type f -size +10M) and show it in the results.

💡 Tip: Commands generated from the search prompt are for one-time use and are not saved automatically. If you want to save a command after generating it this way, you can place it on your terminal and then use the bookmark hotkey (Ctrl+B).

For a more direct workflow, use the AI directly in the bookmarking UI. Press Ctrl+B, type your description in the 'Command' field, and press Ctrl+I to suggest it.

Populating Your Library

A great command library is a complete one. Here are three ways to quickly add commands without bookmarking them one by one.

From tldr Pages

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

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.

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

Now you can type tar into the command line and press Ctrl+Space

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

From Community Gists

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.

# Import all commands from a Gist
intelli-shell import https://gist.github.com/lasantosr/137846d029efcc59468ff2c9d2098b4f

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

This makes it simple to load command templates shared by other users directly into your library.

💡 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

You can use the AI when importing to extract and convert commands from any piece of text—a blog post, a tutorial, or even your own shell history file.

# Import command templates from your own history
intelli-shell import -i --ai --history bash

# Or from a URL
intelli-shell import -i --ai "https://my-favorite-cheatsheet.com"

The AI will parse the content, identify potential commands, and convert them into reusable templates with {{variables}}, ready for you to use.

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

Using Variables

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

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

Basic Syntax

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

echo "Hello, {{user}}!"

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

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 suggestion history. You can mark a variable as secret by enclosing it in an extra set of curly braces: {{{secret_variable}}}.

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

When you fill in a secret variable:

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

Providing Default Suggestions

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

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

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

Formatting Input with Functions

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

Syntax: {{variable_name:function1:function2}}

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

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

Here are the available functions:

Functions are applied from left to right.

How Suggestions Are Managed

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

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

This means:

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

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

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

Dynamic Suggestions with 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.

To ensure your workflow is never interrupted, completions run asynchronously in the background. When IntelliShell prompts for a variable that has an associated completion:

• Instantly, you'll see suggestions from your history and matching environment variables.
• In the background, the completion command is executed.
• Once finished, its output (split by newlines) is seamlessly merged into the existing suggestion list.

This non-blocking approach means you can include potentially slow network commands (like kubectl or gh) as completions without ever slowing down your terminal experience.

For instance, to get dynamic suggestions for all local git branches whenever you use a {{branch}} variable in a git command, you can register the following completion:

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

Now, commands like git checkout {{branch}} or git rebase {{branch}} will automatically suggest your local branches, making your workflow faster and less error-prone.

Global Completions

By omitting the --command flag, you create a global completion that applies to a variable name in any command. This is ideal for universally useful variables, like system usernames.

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

It's important to note that IntelliShell always prioritizes specificity. If a command-scoped completion also exists for the same variable, it will always take precedence over the global one.

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

   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 will first prompt for the namespace. Once you select one (e.g., production), it substitutes that value into the pod completion's command, running kubectl get pods -n production ... to get a list of pods only from that specific namespace. Because this runs in the background, you can immediately type a pod name you already know without waiting for the kubectl command to return its list.

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

Workspace File

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

How It Works

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

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

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

Key Behaviors

• 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, they are loaded fresh for each session
• Top Priority: Workspace-specific commands always appear at the top of your search results, making them easy to find
• Version Controllable: Since it's a plain text file, you can commit .intellishell to your Git repository to share common workspace commands with your entire team

Use Cases

Workspace-specific commands and completions are ideal for:

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

File Format

The .intellishell file uses the same simple text format as the import and export commands. Any commented line (#) before a command is treated as its description, you can check IntelliShell's own file on the repo.

Here is an example .intellishell file for a terraform repo:

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

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

Syncing and Sharing

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

Commands are stored in a simple, human-readable text format that supports commands, aliases, descriptions, and dynamic variable completions, making the files easy to edit by hand.

Any commented line (#) directly preceding a command is treated as its description, and any line starting with a dollar sign ($) is treated as a completion.

# --------------------------------------------------------------
#   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-aware 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/Preferences/org.IntelliShell.Intelli-Shell/config.toml
• Windows: %APPDATA%\IntelliShell\Intelli-Shell\config\config.toml

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

Configuration Topics

This section is broken down into the following chapters:

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

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

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

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

• 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/macOS, unless overridden by XDG_DATA_HOME)
# - ~/Library/Application Support/org.IntelliShell.Intelli-Shell (on macOS)
# - %APPDATA%\IntelliShell\Intelli-Shell\data (on Windows)
data_dir = ""

Overriding with INTELLI_STORAGE

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

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

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

Update Checks

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

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

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

UI Rendering Mode

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

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

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

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

Gist Integration

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

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

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

Search

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

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

Standard Controls

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

List & Tab Navigation

Text Cursor Movement

Text Editing

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

Theming

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

Style Formatting

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

Supported Modifiers

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

• bold
• dim
• italic
• underline

Supported Colors

Colors can be specified in several formats:

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

Configuration Options

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

Default Configuration

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

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

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]

Commands

The commands can be thought of in three main categories: core workflow, data management, and library expansion. 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

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 line. See the Installation Guide for a full list of integration variables or the Keybindings Configuration for in-app bindings.

Installation and Command Issues

"command not found: intelli-shell"

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

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

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

"Permission Denied" errors on Linux/macOS

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

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

General Usage

How do I edit or delete a bookmarked command?

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

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

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

Where is my data stored?

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

• Configuration File:

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

• Data Files (Database, Logs):

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

How can I sync commands between machines?

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

Imported commands are not appearing

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

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

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

Variable suggestions are not synced

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

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

Advanced Troubleshooting

Enabling logs

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

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

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

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

Resetting to defaults

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