Shell integration

I personally like to alias bld to howzit -r. If you define a function in your shell, you can have it default to "build" but accept an alternate argument. There's an example for Fish included, and in Bash it would be as simple as howzit -r ${1:build}.

For completion you can use howzit -L to list all topics, and howzit -T to list all "runnable" topics (topics containing an @directive or run block). Completion examples for Fish are included in the fish directory.

Using topics as shell commands (fish and zsh)

If you want to be able to type a topic name as a bare command (without prefixing it with howzit -r) and have it automatically run the corresponding topic when one exists in the current context, there are example hooks for both fish and zsh in the repo.

These hooks rely on the --test-search flag, which exits with status 0 if a search term matches at least one topic (and 1 otherwise), without producing normal output.

• fish: fish/functions/howzit_command_not_found.fish

  This defines a fish_command_not_found handler. When you type an unknown command:

  • It runs howzit --test-search CMD.
  • If that exits 0 (a topic matches), it runs howzit -r CMD [args...].
  • If it exits non‑zero, it falls back to fish's normal “unknown command” behavior.

  Effectively, if you're in a directory where howzit can see a build note and there is a topic named (or matching) deploy, typing:

  deploy

  will behave the same as:

  howzit -r deploy

• zsh: zsh/howzit-command-not-found.zsh

  This defines a command_not_found_handler that behaves the same way:

  • For an unknown command CMD, it runs howzit --test-search CMD.
  • If that succeeds, it runs howzit -r CMD [args...].
  • Otherwise, it prints the standard zsh: command not found: CMD message.

In both shells, this gives you a smooth “topic as command” experience: if a matching howzit topic exists in the current hierarchy, the topic runs; if not, you get your shell's normal “command not found” behavior.