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.
• Either an ANTHROPIC_API_KEY, which the default provider: anthropic uses, or a logged-in claude or codex CLI, which uses your Claude or ChatGPT subscription and needs no API key. OpenAI and compatible APIs are covered in 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.

Connect a model

Pick one. Either way, nothing else is required.

With an 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

With your Claude or ChatGPT subscription

No API key needed. If you’re logged into Claude Code or Codex, including on a seat your company provides, smartly shells out to that session. Log in first if you haven’t:

claude login    # or: codex login

Then run smartly config init and set the provider in the config.yaml it writes:

provider: claude-cli     # or codex-cli

providers:
  claude-cli:
    model: haiku         # required for claude-cli

Or skip the config and pass it for one call with --provider claude-cli --model haiku. smartly onboard walks through the same choice. Each request spawns a CLI process, so it is slower than an API key; the full tradeoffs are in Providers.

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.