Operations and CLI

The couchset CLI is an explicit admin surface: plan and apply against a trusted config that exports your client. It never discovers projects, never provisions on import, and never silently drops indexes or Eventing functions.

Install and help

npx couchset --help
# or, after npm install -g / local bin:
couchset --help

couchset model User only prints a starter defineModel snippet — it does not write files.

Config

Admin commands require --config ./couchset.config.cjs. The file is trusted application code. It must export db as a CouchsetClient with models registered. Export eventing for eventing plan.

// couchset.config.cjs — illustrative; keep free of provisioning side effects
const { createCouchsetClient, defineModel } = require('couchset/next');

const users = defineModel({
  name: 'User',
  scope: 'app',
  collection: 'users',
  indexes: [{ name: 'idx_user_email', fields: ['email'] }],
});

const db = createCouchsetClient({
  connectionString: process.env.COUCHBASE_URL,
  username: process.env.COUCHBASE_USERNAME,
  password: process.env.COUCHBASE_PASSWORD,
  bucketName: process.env.COUCHBASE_BUCKET || 'app',
  models: [users],
});

module.exports = { db };
// module.exports = { db, eventing }; // when using Eventing plan

Loading the config can run your application code. Keep it free of ensure* / apply* at import time. The CLI always shutdown()s the client when finished.

Commands

npx couchset inspect --config ./couchset.config.cjs
npx couchset collections plan --config ./couchset.config.cjs
npx couchset collections apply --config ./couchset.config.cjs
npx couchset indexes plan --config ./couchset.config.cjs
npx couchset indexes apply --config ./couchset.config.cjs --plan ./plan.json
npx couchset search-indexes plan --config ./couchset.config.cjs
npx couchset search-indexes apply --config ./couchset.config.cjs --plan ./search-plan.json --allow-replace
npx couchset eventing plan --config ./couchset.config.cjs

Command	Behavior
`inspect`	Model names, scopes, collections, index / Search index names — no secrets
`collections plan`	Read-only `{ scope, collection, status: 'create' \| 'matching' }[]`
`collections apply`	Create-only ensure; no `--plan` file
`indexes plan`	JSON GSI plan (`create` / `matching` / `replace`, physical `createAs`, optional `replaces`)
`indexes apply --plan`	Apply exactly the reviewed JSON; CLI does not expose GSI old-index drop
`search-indexes plan`	Search create/match/replace with catalog identity (stale plans fail)
`search-indexes apply --plan`	Apply reviewed Search plan; replacement also needs `--allow-replace`
`eventing plan`	Definition drift / stale owned names only — not deploy/lifecycle readiness

Plan/apply commands print JSON. Index/Search apply requires --plan ./plan.json (reviewed file). There is no CLI Eventing apply / prune — deploy through the Eventing application API after review.

Recommended workflow

inspect — confirm the config sees the models you expect.
collections plan then collections apply if anything is create.
indexes plan → save JSON → review → indexes apply --plan ….
Same for Search when you use Search indexes.
eventing plan for definition drift; deploy with eventing.apply() in app code.

Programmatic equivalents live under Provisioning and transactions and Search, vector, and geospatial.

Pitfalls

Pointing --config at code that provisions on load.
Applying an unreviewed or stale Search plan (catalog UUID mismatch).
Expecting Search replace without --allow-replace.
Expecting the CLI to drop old GSI indexes or deploy Eventing.