# @ductape/cli

## AI-led codebase migration

Create and pass project-level E2E tests against the original codebase first, then bind them with
`ductape migration-e2e init`. Run `ductape migrate-codebase --e2e-baseline <manifest>`; the default is a
separate new codebase. Migration commands record advisory or verification evidence and never generate
application source. Finish with the unchanged original suite through `migration-e2e final`.

Terminal interface for Ductape — **same transport as the Workbench** (encrypted sdk-proxy / db-proxy / graph-proxy).

## Install

```bash
cd cli
npm install
npm run build
```

### Global `ductape` command (optional)

`npm link` installs into npm’s global prefix. If you see `EACCES` on `/usr/local/lib/node_modules`, that prefix is owned by root (common with the system Node installer). Use one of these:

**Option A — run without linking (no sudo)**

```bash
npm exec ductape -- login
npm exec ductape -- resources storage list
# or: node dist/index.js login
```

**Option B — user-owned global prefix (recommended for `npm link`)**

```bash
mkdir -p ~/.npm-global
npm config set prefix "$HOME/.npm-global"
# Add to ~/.zshrc (or ~/.bashrc):
#   export PATH="$HOME/.npm-global/bin:$PATH"
source ~/.zshrc
cd cli && npm link
ductape --help
```

Do not use `sudo npm link`; it mixes root-owned globals with your normal user.

## Quick start

```bash
ductape install
ductape login                    # uses `cloud` profile (https://api.ductape.app)
ductape login --browser google   # browser OAuth; returns to the CLI automatically
ductape login --browser github
# Local platform (UI + API on your machine):
ductape profiles use local
ductape start
ductape login --profile local

# Workbench UI locally, cloud API (no local backend):
ductape start --remote --build
ductape login
ductape init --link
ductape resources storage list
ductape generate snippet storage upload -l typescript -o upload.ts
```

## Command overview

```
ductape login|logout|whoami|install
ductape profiles list|use <name>
ductape workspaces list|current|use   # interactive picker on login/link/use
ductape products list|get|create|update|delete
ductape apps list|get|create|update|delete|import
ductape init|link|unlink
ductape start|stop|status   # status explains proxy 502 when backend is down
ductape resources <type> <verb>   # CRUD via sdk-proxy (interactive prompts or -f JSON)
ductape events topics validate --dir ductape/events
ductape events topics create-all --dir ductape/events
ductape cloud connections list|create|get|update|complete|validate|delete
ductape cloud resources list|import|provision …
ductape db <verb>                 # db-proxy runtime
ductape graph <verb>              # graph-proxy runtime
ductape secrets <verb>
ductape marketplace search payments --json
ductape marketplace get paystack --json
ductape generate payload|snippet …
ductape completion bash|zsh
```

## Event topic assets

Ductape topic assets are individual, directly importable files at
`ductape/events/<topic-tag>.topic.json`. Each file contains exactly one topic object whose fully
qualified `tag` is `broker-tag:topic-tag`; the filename uses the unqualified topic portion.
Aggregate catalogues, manifests, envelope registries, and custom event registries are rejected.

Run `ductape events topics validate --dir ductape/events --json` in CI. `create-all` validates every
file and publisher reference before performing its first remote mutation.

## Documentation

Full reference: [docs/docs/cli/](../docs/docs/cli/index.mdx)

## Tests

```bash
npm test
```

## Changelog

See [CHANGELOG.md](./CHANGELOG.md).