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 projects               # confirms the account and lists its projects
coduck login                  # browser opens, click Approve
coduck create-existing        # in your project folder — creates a coduck.json
coduck projects               # confirms the account and lists its projects

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

If you are a coding agent, continue by making and testing the requested changes yourself. Then use commands such as coduck push, coduck draft create, coduck changes, and coduck deploy to operate the project. See the commands reference for the full workflow and the intentionally exceptional CoDuck project-agent commands.

#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