Usage — smartly

The shape of a request

smartly <your request in plain English>

No quoting required — everything after the flags is the sentence. smartly generates one shell command and, by default, runs it immediately.

smartly show hidden files sorted by size

ls -lahS

smartly replace api.example.com with api.internal in every yaml file

find . -name '*.y*ml' -exec sed -i '' 's/api\.example\.com/api.internal/g' {} +

What you get

One command line. Pipes, && and redirects inside that line are fine. smartly will not produce a multi-step script — if a request genuinely needs several steps, ask for the steps one at a time.

A command for your operating system. smartly accounts for GNU (Linux) versus BSD (macOS) userland differences, so the same request produces sed -i '' on macOS and sed -i on Linux.

A command grounded in where you are. By default smartly sends a capped directory listing plus your git branch, status and worktrees, so a request like “delete all my branches that are already merged into main” resolves against what is actually there. See Context for the three levels and what each one sends.

Per-invocation flags

These override configuration for a single call and change nothing on disk.

Flag	Effect
`--provider <name>`	Use `anthropic`, `openai`, `claude-cli` or `codex-cli` for this call.
`--model <name>`	Override the model for whichever provider is active.
`--context <level>`	Use `none`, `light` or `full` context for this call.
`--confirm`	Force the `[y/N]` prompt, whatever the configured mode.
`-y`, `--yes`	Force auto-run, whatever the configured mode.
`--dry-run`	Print the command. Ask nothing, run nothing.
`--learn`	Break the command down piece by piece. Run nothing. Also `--explain`, `--teach`.

--confirm and -y/--yes are mutually exclusive.

smartly --provider codex-cli --context none show me disk usage by directory
smartly --dry-run delete all my branches that are already merged into main
smartly --confirm kill whatever is listening on port 3000

Learning from the command

--learn shows how smartly got from your sentence to the command: a one-line summary, then each piece with what it does. Nothing runs.

$ smartly --learn find files over 100mb changed this week
→ find . -type f -size +100M -mtime -7

  Finds files over 100 MB changed in the last week, from here down.

  find .       search from the current directory down
  -type f      files only, skip directories
  -size +100M  larger than 100 MB
  -mtime -7    modified in the last 7 days

In a color terminal each piece is tinted by what it is: the command in bold, flags blue, quoted text cyan, operators such as | and > magenta. The same piece is the same color on the → line and in the breakdown, so you can match them at a glance. The colors come from your terminal’s own palette, and a key underneath says which is which. With NO_COLOR set, the words carry it alone.

The command is generated exactly as it would be without the flag. The breakdown is a second model call, which takes a little longer, and it is the model’s reading of the command, so check anything surprising against man.

--explain and --teach are the same flag.

Trying a provider without committing to it

--provider and --model are the cheapest way to compare backends, because neither writes to your config file:

smartly --provider claude-cli --model haiku --dry-run list the largest files here

If that provider needs setup you have not done yet, smartly fails with an actionable error rather than quietly falling back to another one. See Providers.

Limitations

One shell command line per invocation. No multi-step scripts.
bash and zsh on Linux and macOS. Windows and PowerShell are not supported yet.
The OpenAI provider ships with no default model — you must set providers.openai.model yourself.
claude-cli and codex-cli need the respective CLI installed and separately logged in, and their error classification is best-effort.