Skip to main content

Install Toby

You can install Toby with the install script, from a release binary, or from source.

The install script downloads the latest macOS release archive and installs the toby binary to ~/.local/bin. Bundled helper binaries (toby-listener, whisper-cli) go to ~/.toby/helpers/ and first-party plugins (toby-plugin-sample, toby-plugin-azuread, toby-plugin-gmail, toby-plugin-todoist, toby-plugin-jira, toby-plugin-websearch, toby-plugin-applecalendar, toby-plugin-macos) to ~/.toby/plugins/, so only toby is added to your PATH. It does not require sudo.

After installing binaries, the script runs toby whisper setup to download the default local transcription model (ggml-base.en.bin) into ~/.toby/models/. If that step fails (for example offline install), run toby whisper setup later.

On macOS, run:

curl -fsSL https://raw.githubusercontent.com/kshehadeh/toby/main/install-toby.sh | bash

If you already cloned the repo, you can run the script locally:

./install-toby.sh

The script picks the right asset for your system:

PlatformArchitectureRelease asset
macOSApple Silicontoby-darwin-arm64.zip
macOSInteltoby-darwin-x64.zip

After it finishes, verify the install:

toby --help

If toby is not found, the script prints how to add ~/.local/bin to your shell PATH (zsh, bash, or fish). Open a new terminal or source your profile after updating PATH.

Optional settings​

VariablePurpose
TOBY_INSTALL_DIRInstall directory (default: ~/.local/bin)
TOBY_VERSIONInstall a specific release tag, e.g. v0.9.2
TOBY_REPOGitHub repo as owner/name (default: kshehadeh/toby)
GITHUB_TOKENOptional token to raise GitHub API rate limits

Example — install to a custom directory:

TOBY_INSTALL_DIR="$HOME/bin" curl -fsSL https://raw.githubusercontent.com/kshehadeh/toby/main/install-toby.sh | bash

Option 2: Release binary (manual)​

If you prefer to download the binary yourself:

  1. Open the Toby releases page.
  2. Download the archive for your platform (see the table above).
  3. Extract it, then put toby on your PATH, helpers under ~/.toby/helpers/, and plugins under ~/.toby/plugins/:
unzip toby-darwin-arm64.zip
chmod +x toby toby-listener whisper-cli toby-plugin-*
mkdir -p ~/.toby/helpers ~/.toby/plugins
mv toby-listener whisper-cli ~/.toby/helpers/
mv toby-plugin-* ~/.toby/plugins/
sudo mv toby /usr/local/bin/
toby whisper setup
  1. Verify the install:
toby --help

Option 3: Install from source​

  1. Clone the repository:
git clone https://github.com/kshehadeh/toby.git
cd toby
  1. Install dependencies and build:
bun install
bun run build
  1. Run Toby:
bun run dev -- --help

When developing from source, prefix commands with bun run dev -- (for example, bun run dev -- chat). Build and install first-party plugins before using Gmail, Azure AD, Web Search, or other plugin integrations:

bun run build:plugins
toby plugins doctor

To link individual plugins during development:

toby plugins install ./dist/toby-plugin-gmail --link --force
toby plugins install ./dist/toby-plugin-azuread --link --force
toby plugins install ./dist/toby-plugin-websearch --link --force

Next steps​