Ahoy

Abstract

1. Introduction

Ahoy gives each of your projects its own CLI app with zero code and zero dependencies. Write your commands in a YAML file, and Ahoy turns them into a real command line tool with a command listing, per-command help, shell tab completion, and the ability to run your commands from any subdirectory.

Automate and organise your workflows, no matter what technology you use.

It was created to help with running interactive commands inside Docker containers, but it works just as well for local commands, aliases for commands with complex parameters, commands over ssh, or anything else you would otherwise run by hand.

2. Objective

Create shareable, self-documenting command-line tools from simple YAML files. Easily wrap shell, npm, docker... anything, to standardize your processes and make the lives of the people working on your project better.

This project demonstrates how Go, Docker can be applied to a real-world Blockchain & Cloud Computing problem.

3. Key Features / Modules

• Non-invasive - wraps the commands and scripts you already use.
• Consistent - commands always run relative to the .ahoy.yml file, but can be called from any subfolder.
• Visual - see all your commands in one place with helpful descriptions.
• Flexible - each repo or workspace gets its own commands.
• Fully interactive - shells like MySQL and interactive prompts still work.
• Command templates - use regular bash syntax like "$@" or $1.
• Imports - split commands across multiple files, with "last in wins" for duplicates, and optional: true to skip missing files gracefully.
• Aliases and descriptions - give commands short alternative names and longer multi-line help text.
• Environment variables - load one or more env files at both file and command level. Ahoy also injects AHOY_COMMAND_NAME and AHOY_CMD into every command.
• Shell completion - commands and help are self-documenting. There's a dedicated Zsh plugin at ahoy-cli/zsh-ahoy.

4. Technology Stack

5. System Requirements

General requirements for this technology stack — check the README for exact versions.

• Go 1.20 or later
• Git (to clone the repository)

6. Installation & Setup

git clone https://github.com/ahoy-cli/ahoy.git
cd ahoy

brew install ahoy

os=$(uname -s | tr '[:upper:]' '[:lower:]') && architecture=$(case $(uname -m) in (x86_64 | amd64) echo "amd64" ;; (aarch64 | arm64 | armv8*) echo "arm64" ;; (armv7*) echo "armv7" ;; (armv6*) echo "armv6" ;; esac) && { [ -n "$architecture" ] || { echo "Unsupported architecture: $(uname -m)" >&2; false; }; } && 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

# Download an example config into your project
ahoy config init

# See what you can run
ahoy

Full setup instructions are in the project README.

7. Future Enhancements

Suggested extensions you can add to make this your own project.

• Add a CI/CD pipeline with GitHub Actions
• Deploy to a public test network or cloud free tier
• Add monitoring and cost alerts

8. Viva / Review Questions

Common questions examiners ask for projects in this domain.

1. Why does this problem need a blockchain or cloud-native design?
2. Explain the smart contract / infrastructure components and how they interact.
3. How are gas costs or cloud costs kept under control?
4. How is the system secured (keys, IAM, access control)?
5. How would the solution scale to many more users?

9. Source Code & License

This project is developed by ahoy-cli and published on GitHub under the MIT License. Please follow the license terms and credit the original author when you use or modify this code.