shell-use

[!WARNING] Work in progress. shell-use is still being built out, so commands and behavior may change between releases & installation instructions may not yet work.

shell-use is a rust powered cli for controlling, inspecting, testing, and recording shell sessions and terminal apps. It supports all standard terminal actions (send keys, mouse clicks) & user actions (screenshot, record sessions), & testing (matches screenshot, contains text). shell-use supports Windows, Linux, & macOS and it supports a wide range of shells (see Supported shells).

Install

homebrew (macOS/linux)

brew tap microsoft/shell-use https://github.com/microsoft/shell-use
brew install shell-use

winget (windows)

winget install Microsoft.ShellUse

download from releases

Download the latest release.

Quick start

Run a command and check the result:

shell-use open                  # start a shell session (auto-starts the daemon)
shell-use submit "echo hello"   # type the command, press Enter
shell-use wait command          # block until it finishes
shell-use expect text "hello"   # assert it showed up
shell-use expect exit-code 0    # assert it exited 0
shell-use close

Drive a full-screen TUI the same way:

shell-use run vim file.txt
shell-use wait idle             # let the screen settle
shell-use press i
shell-use type "some text"
shell-use press Escape : w q Enter
shell-use wait exit

Built for agents

shell-use is an AI native CLI. Point yours at the built-in docs and it can serve itself the rest:

• shell-use agent-context prints versioned JSON for every command, flag, enum, default, and exit code. It is generated from the CLI, so it cannot drift from the real surface.
• shell-use usage prints a one-screen cheatsheet.
• shell-use skill prints the full workflow guide (SKILL.md).

Skill quick start

# ~/.agents or ~/.claude instead to install it for