Getting Started with Ahoy

Installation

macOS

brew install ahoy

Linux

os=$(uname -s | tr '[:upper:]' '[:lower:]') && architecture=$(case $(uname -m) in x86_64 | amd64) echo "amd64" ;; aarch64 | arm64 | armv8) echo "arm64" ;; *) echo "amd64" ;; esac) && sudo wget -q https://github.com/ahoy-cli/ahoy/releases/latest/download/ahoy-bin-$os-$architecture -O /usr/local/bin/ahoy && sudo chown $USER /usr/local/bin/ahoy && chmod +x /usr/local/bin/ahoy

Or download the latest release from GitHub and place the binary somewhere in your $PATH.

Windows (WSL2)

Use the Linux instructions above.

Verify it’s working:

ahoy --version

Start with examples

The quickest way to get going is to initialise a project with our curated examples file. It includes 30+ ready-to-use commands for common development workflows.

cd my-project
ahoy config init

This creates an .ahoy.yml in the current directory. Run ahoy on its own to see what’s available:

ahoy

Tip

Want to inspect the file before downloading? The examples file is at examples/examples.ahoy.yml in the repository.

Write your own commands

Create an .ahoy.yml file in your project root:

ahoyapi: v2

commands:
  hello:
    usage: Say hello to someone
    cmd: echo "Hello, $1!"

  start:
    usage: Start the dev environment
    cmd: docker-compose up -d

  logs:
    usage: Follow container logs
    cmd: docker-compose logs -f $@

Run your commands from anywhere in the project tree:

ahoy hello World   # Hello, World!
ahoy start
ahoy logs web
ahoy              # Shows all commands and their usage text

Note

Ahoy searches up the directory tree for .ahoy.yml, so you can run commands from any subdirectory in your project.

Next steps

• Writing Commands - practical patterns and real-world examples
• Shell Autocompletion - set up tab completion
• YAML Schema Reference - complete field-by-field reference
• CLI Reference - all command-line flags and built-in commands