Guide · Open source

How to use autocomplete: install, run and write specs

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

withfig/autocomplete is an MIT-licensed collection of declarative completion specs for popular command-line tools such as git, npm, docker and aws. Its README says these specs power IDE-style suggestions in your terminal through Amazon Q Developer CLI, formerly Fig. This guide explains what the project is, how to get suggestions working, and how to create or fix a spec.

Figwithfig/autocomplete · ★ 25.2k · MIT Install options & downloads

Quick start

1Check your platform. Confirm you are on macOS, since the README says Amazon Q for command line is macOS-only for now.
2Install Amazon Q. Run brew install amazon-q or download the app from AWS, then launch it to finish setup.
3Install Node and pnpm. Install Node.js and pnpm, the package manager the repo uses.
4Clone your fork. Fork withfig/autocomplete on GitHub and clone your fork with git clone.
5Install packages and enable dev mode. Run pnpm install, then pnpm dev.
6Test an example spec. Run pnpm create-spec abc, then type abc and a space in your terminal to see the example suggestions.

What does withfig/autocomplete do?

The README describes a completion spec as a declarative schema that specifies the subcommands, options and args for a CLI tool. Amazon Q uses these schemas to generate suggestions as you type a command in your shell.

The repository is written in TypeScript and holds specs for many tools. It is mainly a spec collection rather than a package you install from a package manager.

Check whether your system is supported

The README says Amazon Q for command line is only available on macOS for now. Linux and Windows support is still in progress, and the README links to discussions for each.

The FAQ in the README lists native macOS Terminal, iTerm, Tabby, Hyper, Kitty, WezTerm and Alacritty, plus the integrated terminals of VSCode, JetBrains IDEs, Android Studio and Nova.

macOS: supported
Linux and Windows: not yet supported according to the README

Install Amazon Q on macOS

Launch the app after it downloads. The README notes that the app is needed to set up Amazon Q for command line. You can install it with Homebrew or download the DMG from AWS.

Homebrew route: run the command below
DMG route: download from the AWS documentation page linked in the README

brew install amazon-q

Set up the repo and turn on dev mode

To work on specs, you need Node, pnpm and Amazon Q for command line. Fork the repo on GitHub, then clone your fork. The README suggests adding the original repo as an upstream remote.

Run pnpm install to install packages, then pnpm dev to turn on dev mode. The README says that in dev mode, specs are read from the build folder and generators run every keystroke.

Install pnpm first, since the repo uses it as its package manager
Replace YOUR_GITHUB_USERNAME with your own GitHub username

git clone https://github.com/YOUR_GITHUB_USERNAME/autocomplete.git autocomplete
cd autocomplete

# Add withfig/autocomplete as a remote
git remote add upstream https://github.com/withfig/autocomplete.git

# Install packages
pnpm install

# Turn on "dev mode"
pnpm dev

Create an example spec and test it in your terminal

The README's walkthrough creates a sample spec called abc using pnpm create-spec. After dev mode is on, type abc followed by a space in your terminal and the example spec should appear.

Specs are written in TypeScript in the src folder. On save, they are compiled to the build folder.

Edit specs in the src/ folder
Compiled output goes to the build/ folder

# Create an example spec (call it "abc")
pnpm create-spec abc

Run the other package.json commands

The README lists three helper scripts. pnpm test typechecks all specs in src. pnpm build compiles TypeScript specs from src to build. pnpm lint:fix lints and fixes issues.

pnpm test
pnpm build
pnpm lint:fix

Contribute fixes or new specs

The README lists contributions it welcomes: new completion specs, fixes for missing subcommands, options or arguments, generators for argument suggestions, better descriptions and icons, and themes. If you cannot contribute code, you can open an issue on GitHub.

New completion specs
Fixes for missing subcommands, options or arguments
Generators for argument suggestions
Better descriptions and icons

What people use it for

Getting git, npm, docker or aws subcommand suggestions while typing in a macOS terminal
Fixing a missing option in an existing spec for a tool you use
Adding a new spec for a CLI that has none
Learning how declarative command schemas map to terminal suggestions

Frequently asked questions

How do I install withfig autocomplete?

The repo is installed by cloning your fork, then running pnpm install and pnpm dev. The README also says you need Amazon Q for command line installed first, which you can get with brew install amazon-q on macOS.

Does autocomplete work on Linux or Windows?

The README says Amazon Q for command line is only available on macOS for now. Linux and Windows support is still in progress, and the README links to discussions for each.

Is withfig autocomplete free and open source?

The repository is licensed under MIT, according to the project metadata. The README also says Amazon Q Developer CLI, formerly Fig, is open source and points to aws/amazon-q-developer-cli.

What requirements do I need?

The README lists Node.js, pnpm and Amazon Q for command line. Node and pnpm are used for the repo, and Amazon Q provides the suggestions in your terminal.

What are alternatives to this project?

The source names zsh-autosuggestions, fish shell and carapace as comparable projects. The README does not compare them directly, so check each one's documentation for details.

Amazon Q for command line doesn't work for me. What should I do?

The README says to run q doctor to debug issues with your installation. If that does not solve it, open a question in the aws/q-command-line-discussions GitHub discussions.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use this if you are on macOS, want suggestions for common CLIs, or want to write or fix completion specs for tools you use. Pick a different option such as zsh-autosuggestions, fish shell or carapace if you are on Linux or Windows, want a standalone package, or need suggestions without the Amazon Q app.

Install options & downloads