Skip to content

Getting Started

This guide walks you through installing Agent CLI and setting up your first voice-powered workflow.

Prerequisites

Before you begin, ensure you have:

  • uv (recommended) or Python 3.11+
  • A microphone for voice features
  • Speakers for text-to-speech features
  • PortAudio (Linux only): sudo apt install portaudio19-dev or equivalent for your distro

Installation

Option 1: macOS Menu Bar App

For the native Mac app with global shortcuts and automatic local Whisper setup:

brew install --cask basnijholt/tap/agent-cli

See: macOS Menu Bar App

Option 2: CLI Tool Only

If you already have AI services set up or plan to use cloud services (OpenAI/Gemini):

# Using uv (recommended)
uv tool install agent-cli

# Using pip
pip install agent-cli

Option 3: Full Local Setup

For a complete local setup with all AI services:

Tip

Have a GPU? Skip the setup below and run your own Whisper server in one command: 

pip install "agent-cli[faster-whisper]"
agent-cli server whisper
Apple Silicon MLX-only setup: 
pip install "agent-cli[mlx-whisper]"
agent-cli server whisper --backend mlx
See Local Whisper Server for details.

# 1. Install agent-cli
uv tool install agent-cli

# 2. Install all required services
agent-cli install-services

# 3. Start all services
agent-cli start-services

# 4. (Optional) Set up system-wide hotkeys
agent-cli install-hotkeys

install-hotkeys also installs the required audio and llm extras if they are missing.

See: install-services | start-services | install-hotkeys

# 1. Clone the repository
git clone https://github.com/basnijholt/agent-cli.git
cd agent-cli

# 2. Run setup
./scripts/setup-macos.sh  # or setup-linux.sh

# 3. Start services
./scripts/start-all-services.sh

# 4. (Optional) Set up hotkeys
./scripts/setup-macos-hotkeys.sh  # or setup-linux-hotkeys.sh

Verify Installation

agent-cli --version
agent-cli --help

Tip

Short aliases: You can also use agent or ag instead of agent-cli: 

ag --version
agent transcribe --help

Test Your Setup

Test Autocorrect

agent-cli autocorrect "this has an eror"
# Output: this has an error

See: autocorrect

Test Transcription

# List available microphones
agent-cli transcribe --list-devices

# Start transcribing (press Ctrl+C to stop)
agent-cli transcribe --input-device-index 1

See: transcribe

Test Text-to-Speech

agent-cli speak "Hello, world!"

See: speak

Platform-Specific Guides

For detailed installation instructions, see the platform-specific guides:

Platform Guide Notes
macOS app macOS App Native menu bar app
macOS macOS Setup Full Metal GPU acceleration
Linux Linux Setup NVIDIA GPU support
NixOS NixOS Setup Declarative configuration
Windows Windows Setup WSL2 recommended
Docker Docker Setup Cross-platform

First Workflow: Voice Transcription

Here's a typical workflow for using voice transcription:

  1. Copy some text you want to respond to (e.g., an email)
  2. Press your hotkey (Cmd+Shift+R on macOS) to start recording
  3. Speak your response naturally
  4. Press the hotkey again to stop recording
  5. Paste the transcribed text wherever you need it

What's Next?