assist

assist is a command-line AI assistant written in Rust that generates shell commands from natural language descriptions, supporting both POSIX shells and PowerShell.

Features

• Smart Shell Detection: Automatically detects whether to target a POSIX shell (sh) or PowerShell (pwsh/powershell) based on the environment.
• Cross-Platform: Seamlessly works across Linux, macOS, and Windows.
• Interactive Execution: Instantly preview, execute, or copy generated commands to your clipboard.
• Simple Model Selection: Select an AI model using a simple provider:model syntax. Currently, only the google provider is supported.

Installation & Build

Prebuilt Binaries

For a quick setup without a Rust environment, download the precompiled binaries for your platform from the GitHub Releases page.

We provide small, optimized binaries for the following targets:

OS	Architecture / Environment	Archive File
Linux (GNU)	x86_64	assist-x86_64-unknown-linux-gnu.tar.gz
	AArch64	assist-aarch64-unknown-linux-gnu.tar.gz
Linux (musl)	x86_64	assist-x86_64-unknown-linux-musl.tar.gz
	AArch64	assist-aarch64-unknown-linux-musl.tar.gz
macOS	Apple Silicon (AArch64)	assist-aarch64-apple-darwin.tar.gz
	Intel (x86_64)	assist-x86_64-apple-darwin.tar.gz
Windows	x86_64 (MSVC)	assist-x86_64-pc-windows-msvc.zip
	AArch64 (MSVC)	assist-aarch64-pc-windows-msvc.zip

Extract the archive and move the assist (or assist.exe) binary to a directory in your system's PATH.

Tip

Which Linux binary should I choose?

• GNU (-gnu): Dynamically linked against glibc. This is the standard choice for most mainstream Linux distributions (Ubuntu, Debian, Fedora, Arch, etc.).
• musl (-musl): Statically linked against musl libc, reducing runtime library dependencies. It is useful for minimal Linux environments such as Alpine Linux.

Building from Source

If you prefer to compile assist manually, you will need a Rust development environment installed (cargo). Clone the repository and build the binary:

git clone https://github.com/comosense/assist.git
cd assist
cargo build --release

The compiled binary will be available at target/release/assist.

Usage

Prerequisites

Set your API key as an environment variable depending on the AI provider you use.

Note

Currently, only 'Gemini (Google)' is supported. For more details on obtaining a Gemini API key, refer to the Gemini API Getting Started Guide.

For Gemini:

# POSIX Shell (e.g., Bash / Zsh)
export GEMINI_API_KEY="your_api_key"

# PowerShell
$env:GEMINI_API_KEY="your_api_key"

Tip

To avoid having to set the key every time, you can add this line to your shell's profile script (e.g., ~/.bashrc, ~/.zshrc, or $PROFILE for PowerShell).

Run assist followed by a natural language description of the commands you want to generate. As long as the AI model can understand it, you can use any language (e.g., English, Japanese, Chinese):

# English
assist "find all markdown files modified in the last 7 days and count their lines"

# Japanese
assist "過去7日間に変更されたすべてのマークダウンファイルを検索し、その行数をカウントしたい"

# Chinese (Simplified)
assist "查找过去7天内修改的所有 markdown 文件并统计它们的行数"

Example Output

When you run the above, assist connects to the AI model and interactively presents the suggested commands:

Example on POSIX Shell

Generating command(s)...

Suggested Command(s):
find . -type f -name '*.md' -mtime -7 -exec wc -l {} +

[e] Execute
[c] Copy
[x] Cancel

>

Example on PowerShell

Generating command(s)...

Suggested Command(s):
Get-ChildItem -Path . -Recurse -Filter *.md | Where-Object { $_.LastWriteTime -ge (Get-Date).AddDays(-7) } | Select-Object FullName, @{Name='LineCount'; Expression={(Get-Content $_.FullName | Measure-Object -Line).Lines}}

[e] Execute
[c] Copy
[x] Cancel

>

Warning

• The output above is just one example. The suggested commands will vary depending on the AI model and environment you use.
• Always review and understand the suggested commands carefully before executing them.
• Commands are generated by AI and may contain errors, unintended behavior, or destructive operations.

Options

Usage: assist [OPTIONS] <PROMPT>...

Arguments:
  <PROMPT>...     Natural language description of the commands to generate

Options:
  -m, --model-path <PATH>   AI model to use (Format: provider:model)
                            If omitted, uses the 'ASSIST_MODEL_PATH' environment variable
                            Falls back to 'google:gemini-flash-latest' if the environment variable is not set
  -k, --key <KEY>           API key for the AI model
                            If omitted, the corresponding environment variable is used
  -s, --shell <SHELL>       Shell to generate commands (sh, pwsh, powershell)
                            If omitted, the shell is auto-detected
  -h, --help                Print help
  -V, --version             Print version

Examples

Use a specific model

# English
assist -m google:gemini-3.6-flash "list all listening ports with their process names"

# Japanese
assist -m google:gemini-3.6-flash "リッスンしているすべてのポートとプロセス名の一覧を表示する"

# Chinese (Simplified)
assist -m google:gemini-3.6-flash "列出所有正在监听的端口及其进程名称"

Alternatively, you can set the ASSIST_MODEL_PATH environment variable to use a specific model without passing the -m (--model-path) option every time:

# POSIX Shell (e.g., Bash / Zsh)
export ASSIST_MODEL_PATH="google:gemini-3.6-flash"

# PowerShell
$env:ASSIST_MODEL_PATH="google:gemini-3.6-flash"

Tip

To avoid having to set the key every time, you can add this line to your shell's profile script (e.g., ~/.bashrc, ~/.zshrc, or $PROFILE for PowerShell).

Use a specific API Key

# English
assist -k your_api_key "create a compressed tarball of the src directory"

# Japanese
assist -k your_api_key "src ディレクトリの tarball を作成する"

# Chinese (Simplified)
assist -k your_api_key "为 src 目录创建一个压缩的 tarball 归档"

Warning

Passing the API key via the -k (--key) option is convenient, but please note that command-line arguments may be recorded in your shell history or visible to other users via process monitoring tools (such as ps). It is recommended to use this option only for temporary testing and rely on environment variables for regular use.

Specify the target shell

By default, assist automatically detects whether to target a POSIX shell or PowerShell based on the environment. However, you can explicitly specify the target shell using the -s (--shell) option.

This is particularly useful if you are working in one environment but need to generate a script or command for another (e.g., generating a PowerShell command while using Bash, or vice versa).

Supported values: sh, pwsh, powershell.

# Generate a PowerShell command while working in a POSIX shell
assist -s pwsh "list all listening ports with their process names"

# Generate a POSIX shell command while working in PowerShell
assist -s sh "find all markdown files modified in the last 7 days"

Disclaimer

Commands generated by assist are produced by AI and may contain syntax errors, unintended behavior, or destructive operations.

• Verify before use: Always carefully review and understand the suggested commands before executing them.
• No liability: The author(s) and contributors of this tool assume no responsibility or liability for any damage, data loss, or other adverse consequences resulting from the use of generated commands. Use at your own risk.

License

This project is open-source under the MIT License.