Some things to keep in mind when using ahoy:

• You always need a .ahoy.yml file - This is where ahoy gets it’s configuration. If the current directory doesn’t have that file, it will recursively look at all the parent directories for one until it either finds it, or fails with an error. This means that each project should have an ahoy file at it’s root to work, but you can be in any subdirectory and ahoy will still find the right file.
• Commands are always run from the directory where .ahoy.yml is - That’s really helpful because no matter where you run ahoy from, the commands will be run from a consistent directory.
• Bash is what is actually running the commands - everything that’s within a “cmd” definition is piped into bash, so whatever you can do with bash, you can do in an ahoy command if you want to create something more complex than a single one-line command. This also means that each command runs in a bash subshell, which is usually fine since all environment variables are copied in, but you won’t be able to affect the parent shell.. for example, changing the user’s current directory or ENV variables.
• Easily debug using –verbose - You can always get the details of what’s actually being run in a command with the -v or the –verbose flag.
• Subcommands come from imported ahoy.yml files - You can import another command files that use the ahoy yaml format as subcommands. This is useful to split up types of commands into different files and so the list of commands isn’t as long. For example, we do this with the dkan command, which just imports dkan/.ahoy/dkan.ahoy.yml. All those commands are then listed by typing ahoy dkan
• Ahoy uses the {{args}} placeholder with a commands arguments - Similar to Drupal templates, ANY arguments added after a command are passed into {{args}}. If you use {{args}} in your command, the actual arguments will be swapped out before the command is run. If {{args}} is used multiple times in a command, all instances are replaced. This is necessary so we can pass arguments along into the script, but adds a lot of flexibility.
• You can use ahoy commands within other commands - This is really powerful! You can define helper commands to further abstract where commands are run (ie. locally vs ssh, vs docker), or simple utilities like ahoy confirm “question that will prompt the user for a yes or no answer” . You can think of these kind of like reusable functions. If you want to hide these utility commands, you can set hide: true in your ahoy file.
• Quotes can be tricky - Sometimes when passing one command into subcommands, you might “loose” your quotes. Try using –verbose to debug what’s happening first, and experiment with both single and double quotes. Keep in mind how the yaml spec processes and escapes quotes. We recommend not starting your command with quotes unless necessary. Multi-line commands (scripts) are best done using cmd: | which allows you to use multiple lines without worrying about quotes.
• Using Environment variables - You can use environment variables from within ahoy commands, but you sometimes need to pay attention to quotes, especially if the ENV variable you intend to use is from another machine (docker, ssh).
• Check your yaml formatting - The script will check your yaml formatting and throw an error if it’s not right, but it doesn’t check everything. Make sure your whitespace and structure are correct if you get yaml errors.