CoDuck Docs

#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
bash
npm install -g @coduckai/cli
npm install -g @coduckai/cli

Verify:

bash
coduck --version
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
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>
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
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.

#Uninstall

bash
npm uninstall -g @coduckai/cli
rm -rf ~/.coduck
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 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
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
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
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:

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.

View raw markdown →Suggest an edit