Howto: Humble command-line assistant

After many years of working with CLI tools (and even writing books on the subject), my skills are far from perfect. So I created Howto — a simple AI command line assistant to help with all kinds of tasks.

Describe the task, and Howto will suggest a solution:

$ howto curl example.org but print only the headers
curl -I example.org

The `curl` command is used to transfer data from or to a server.
The `-I` option tells `curl` to fetch the HTTP headers only, without the body
content.

Howto does not interfere with your workflow. It's not an alternate shell or "intelligent terminal" or anything. You ask, and Howto answers. That's the deal.

Usage: howto [-h] [-v] [-run] [question]

A humble command-line assistant.

Options:
  -h, --help      Show this help message and exit
  -v, --version   Show version information and exit
  -run            Run the last suggested command
  question        Describe the task to get a command suggestion
                  Use '+' to ask a follow up question

However, Howto has some convenience features that you may find useful. Read on for details.

Follow-ups

If you're not satisfied with an answer, refine it or ask a follow-up question by starting with +:

$ howto a command that works kinda like diff but compares differently
comm file1 file2

The `comm` command compares two sorted files line by line and outputs three
columns: lines unique to the first file, lines unique to the second file, and
lines common to both files.

$ howto + yeah right i need only the intersection
comm -12 file1 file2

The `comm` command compares two sorted files line by line.
The `-12` option suppresses the first and second columns, showing only lines
common to both files (the intersection).

If you don't use +, Howto will forget the previous conversation and treat your question as new.

This feature was a game changer for me. Sometimes the AI doesn't get the answer quite right the first time, but with follow-ups it works very well.

You are not limited to a single follow-up, of course. The exchange can be quite lengthy:

$ howto git revert commit
git revert <commit>

Reverts the changes introduced by the specified commit by creating a new commit
with the inverse changes. This is a safe way to undo changes as it doesn't
rewrite history.

$ howto +no, rollback it
git reset --hard <commit>

Resets the current branch to the specified commit, discarding all changes after
that commit. This rewrites history and should be used with caution, especially
on shared branches.

$ howto +keep the changes
git reset --soft <commit>

Resets the current branch to the specified commit, but keeps the changes as
staged changes. This allows you to modify the changes before creating a new
commit.

$ howto +last commit i mean
git reset --soft HEAD^

Resets the current branch to the commit before the last commit (HEAD^), keeping
the changes from the last commit as staged changes.

It's never easy with Git, I guess.

Run command

When satisfied with the suggested command, run howto -run to execute it without manually copying and pasting:

$ howto curl example.org but print only the headers
curl -I example.org

The `curl` command is used to transfer data from or to a server.
The `-I` option tells `curl` to fetch the HTTP headers only, without the body
content.

$ howto -run
curl -I example.org

HTTP/1.1 200 OK
Content-Type: text/html
ETag: "84238dfc8092e5d9c0dac8ef93371a07:1736799080.121134"
Last-Modified: Mon, 13 Jan 2025 20:11:20 GMT
Cache-Control: max-age=2804
Date: Sun, 09 Feb 2025 12:54:51 GMT
Connection: keep-alive

Dead simple, but works reasonably well.

Configure AI provider

Howto works with any OpenAI-compatible provider (like OpenAI itself, OpenRouter, Nebius, Gemini or Grok) and local Ollama models.

To change the provider, set the HOWTO_AI_URL, HOWTO_AI_TOKEN and HOWTO_AI_MODEL environment variables, and you are good to go.

You can also customize the prompt (HOWTO_PROMPT), although the default works pretty well for me.

Final thoughts

I find Howto quite handy in my daily terminal work. If you are interested, check it out:

brew tap nalgeon/howto https://github.com/nalgeon/howto
brew install howto

Or:

go install github.com/nalgeon/howto@latest

See github.com/nalgeon/howto for installation, configuration and usage details.

★ Subscribe to keep up with new posts.