Make the shell yours.
Keep the final say.

Download the wheel (or source archive) and optionally verify it against SHA256SUMS. Cliffy requires Python 3.10 or newer. It is not published on PyPI; install your downloaded file, not a similarly named registry package.

Virtual environment

Run this in the folder containing your downloaded wheel. Activate the environment again in each new terminal where you use Cliffy.

python3 -m venv .venv
. .venv/bin/activate
python -m pip install ./cliffy_ai-0.1.0-py3-none-any.whl
cliffy --version

Prefer isolated global commands? If pipx is installed, use pipx install ./cliffy_ai-0.1.0-py3-none-any.whl. You can also inspect the source on GitHub and install from an extracted source directory.

Every user needs their own provider account and API key. Select a provider and model supported by your account; you are responsible for any provider charges. Default models and availability can change. Cliffy has no hosted model and this site never asks for, receives, or stores your key.

Set your key without printing it

In Bash, the hidden prompt below keeps the value out of your typed command history and suppresses terminal echo. Obtain the key from your provider, not from Cliffy. These exports last for this terminal session; native drafts use exported variables, not a project .env file.

export CLIFFY_PROVIDER=groq
export CLIFFY_MODEL=llama-3.1-8b-instant
read -rs -p 'Groq API key: ' GROQ_API_KEY; echo; export GROQ_API_KEY

For another provider, substitute its name, key variable, and an available model. CLIFFY_API_KEY is also supported as a generic key override. Never paste a literal key into a command, screenshot, repository, or prompt.

Custom OpenAI-compatible endpoint

A custom provider additionally requires an endpoint and model. Replace the example URL and model with your provider's actual values.

export CLIFFY_PROVIDER=custom
export CLIFFY_BASE_URL='https://your-provider.example/v1'
export CLIFFY_MODEL='your-model-id'
read -rs -p 'Custom API key: ' CUSTOM_API_KEY; echo; export CUSTOM_API_KEY

cliffy --check-api is an optional, billable live request, not just a local configuration check. The free/ prefix of an APInex model does not guarantee no charges: verify entitlement and terms with the provider.

With your provider configured, launch an independent native Bash child session. This needs Bash 4+ on Linux, macOS with a newer Bash installed, or WSL. It loads ~/.bashrc, does not edit your profiles, and leaves your normal terminal tab unchanged.

cliffy --shell bash

1. Type a natural-language task, such as show current directory, without pressing Enter.
2. Press Ctrl+G to request a draft. No AI request happens before this shortcut.
3. Review or edit the inserted command. Press Enter to execute it, or Ctrl+C to cancel. Cliffy never executes the AI draft automatically.

Ordinary commands are interpreted by Bash. Aliases, source, export, shell functions, and jobs behave normally in this child. exit returns to your parent shell; the child's working directory and environment are not handed back. Files are still shared with your user account. This is not a sandbox.

The opt-in plugin replaces Ctrl+G in the emacs and vi-insertion keymaps. It does not bind Enter, Tab, or Right. A failed or canceled draft retains the original request; discard or edit it rather than pressing Enter on natural-language text.

Launch cliffy for the existing Python interactive assistant. It supports inline ghost suggestions (accept with Tab or Right at the end of the line), file completion, and reviewed AI workflows:

• % <task> drafts one editable command.
• %% <task> guides a multi-step task with per-step confirmation.
• %%% <task> opens interactive coding with filename and overwrite review.
• ai: <task> generates a unique code file without running it.

This mode is not a full login shell. Simple cd, export, and unset persist inside Cliffy, but compound cd x && command runs in a subprocess. Aliases, source, and other subprocess shell state do not persist. Prefer native Bash when you need actual shell state.

For a native draft, the explicit task and current working directory are sent to the selected provider, not your whole shell environment. In the assistant, text used for AI suggestions or generation may be sent too. A manually entered prompt can contain secrets: never put credentials or private data into AI requests.

The assistant may store commands in local ~/.ai_shell_history and metadata/errors in ~/.ai_shell.log; keep them private and inspect before sharing diagnostics. Your Bash history follows your own Bash configuration. Secret-detection and safety checks are heuristic, not security guarantees. Review generated commands, destinations, and files. cliffy --no-ai disables provider requests; CLIFFY_NO_AI=1 also opts out of suggestions and generation.

Still stuck? Read the project README for additional flags and details.