---
title: Install the CLI
description: How to install, update, and verify the CoDuck command-line interface.
category: cli
order: 1
agent: "Install via 'npm install -g @coduckai/cli'. Requires Node 20+. Verify with 'coduck --version'."
---

# Install the CLI

The CoDuck CLI ships on npm as **`@coduckai/cli`**. It's the same binary used by humans in their terminal and by AI agents calling into CoDuck from their host.

## Requirements

- **Node.js 20** or newer (we use modern fetch + native `Set` semantics)
- A POSIX shell (`bash` / `zsh` / `fish`) or PowerShell
- macOS, Linux, or Windows

## Global install (recommended)

```bash
npm install -g @coduckai/cli
```

Verify:

```bash
coduck --version
```

You should see a JSON line with the current version and the API base URL. If the `coduck` command isn't found, your `npm` global bin isn't on `$PATH` — see Troubleshooting below.

## After installing

Three commands to get going:

```bash
coduck login                  # browser opens, click Approve
coduck create-existing        # in your project folder — creates a coduck.json
coduck chat                   # opens an interactive chat with the AI agent
```

That's it — you're now operating a CoDuck project from your terminal.

## One-off / no global install

```bash
npx @coduckai/cli@latest <command>
```

Useful in CI or on someone else's machine. Slower per invocation because npm has to resolve the package each time.

## Updating

```bash
npm install -g @coduckai/cli@latest
```

The CLI **does not auto-update**. If you want to know what changed between versions, see the changelog on the [npm page](https://www.npmjs.com/package/@coduckai/cli).

## Uninstall

```bash
npm uninstall -g @coduckai/cli
rm -rf ~/.coduck
```

The second command removes your stored credentials and any `coduck.json`-cached state. (Your remote CoDuck account is untouched. To delete that, sign in to [coduck.ai](https://coduck.ai) and use account settings.)

## Output modes

The CLI behaves differently depending on whether its stdout is a terminal:

- **Interactive (TTY)** — pretty tables, colors, spinners, prompts
- **Piped (non-TTY)** — pure JSON, no colors, no prompts, exit codes carry the meaning

Force machine mode at any time with `--json`. Force "fail instead of prompting" with `--no-input`. Both can be combined for use inside agent loops.

```bash
coduck projects --json | jq '.[].id'
coduck deploy --no-input --json
```

## Troubleshooting

### `coduck: command not found`

Your npm global bin directory isn't on `$PATH`. Find it with:

```bash
npm config get prefix
```

The binary lives in `<prefix>/bin`. Add that to your `$PATH` in your shell config (`~/.zshrc`, `~/.bashrc`, etc.).

### `Cannot find module ...node_modules\coduck-cli\...` on Windows

You have a stale shim from a previous attempted install of a different package name. Run these in Command Prompt:

```cmd
npm uninstall -g coduck-cli
npm uninstall -g @coduckai/cli
del "%APPDATA%\npm\coduck.cmd"
del "%APPDATA%\npm\coduck.ps1"
del "%APPDATA%\npm\coduck"
npm install -g @coduckai/cli@latest
```

The `del` commands may say "could not find" for some files — that's fine, keep going. Last command installs fresh.

### `EACCES: permission denied` during install

You're using a system Node where `npm install -g` needs sudo. Don't `sudo npm install` — instead, switch to a user-level Node manager:

- macOS / Linux: [nvm](https://github.com/nvm-sh/nvm) or [fnm](https://github.com/Schniz/fnm)
- Windows: [nvm-windows](https://github.com/coreybutler/nvm-windows)

Then re-run `npm install -g @coduckai/cli` without sudo.

### `EBADENGINE` or "unsupported engine"

Your Node version is below 20. Upgrade Node.

## What's installed

The package contains:

- `bin/coduck.js` — the entry point (calls into compiled JS)
- `dist/` — compiled TypeScript output (~30 KB)
- Runtime deps: `commander`, `chalk`, `@inquirer/prompts`, `cli-table3`, `ora`, `form-data`

No native modules, no postinstall scripts, no telemetry.

## Next

You're ready to [sign in](/docs/cli/auth).