Getting started

What you need

• macOS or Linux, running bash or zsh. Windows and PowerShell are not supported yet.
• Homebrew, or Go if you would rather build the binary yourself.
• An ANTHROPIC_API_KEY, because smartly defaults to provider: anthropic. If you would rather use an existing Claude or ChatGPT subscription, or OpenAI, see Providers.

Install

brew install rizwanreza/tap/smartly

The macOS binaries are signed with an Apple Developer ID and notarized, so Gatekeeper lets them run with no extra steps.

Or build it yourself with Go:

go install github.com/rizwanreza/smartly-cli/cmd/smartly@latest

That puts a binary named smartly in your Go bin directory. If the command is not found afterwards, that directory is not on your PATH:

export PATH="$PATH:$(go env GOPATH)/bin"   # add to ~/.zshrc

export PATH="$PATH:$(go env GOPATH)/bin"   # add to ~/.bashrc

Prebuilt binaries for macOS and Linux are also on the releases page.

Set your API key

Out of the box smartly needs only this. No config file is required.

export ANTHROPIC_API_KEY="sk-ant-..."   # add to ~/.zshrc

export ANTHROPIC_API_KEY="sk-ant-..."   # add to ~/.bashrc

Your first command

Start with --dry-run, which prints the command and does nothing else:

ls -lahS

Drop the flag when you want it to run:

smartly show hidden files sorted by size

Put a gate in front of it

Switch execution mode once and forget about it:

smartly config init                              # writes a default config.yaml

Then set execution.mode in that file. Two gates to choose between:

execution:
  mode: confirm              # ask before every command

execution:
  mode: confirm-destructive  # ask on anything it doesn't recognise as safe

confirm prints every command and waits for [y/N]. confirm-destructive is the middle path: a local classifier reads the generated command and lets recognised-safe ones through, asking on everything else — destructive or unrecognised alike. It is a best-effort seatbelt, not a sandbox, so if you want to see every command, pick confirm.

You can also force the prompt for a single call with --confirm, without changing any config. All of it is covered in Execution and safety.

Next

• Usage — how to phrase requests, and what smartly will and will not generate.
• Shell integration — required if you want a generated cd or export to affect your shell.
• Execution and safety — auto, confirm, confirm-destructive, dry-run, what the classifier counts as destructive, and what gets written to your history log.