Catalog with the CLI

Use scope catalog after connecting the CLI. Start by exporting the resource you want to change, then review a plan before applying it.

Commands write YAML to stdout by default; use --format json for JSON. Diffs, warnings, prompts, and progress go to stderr. Apply and drop return the actual before and after definitions and the destructive flag.

List and export resources

List databases, then schemas and tables within them. Use the names returned by each command in the next command; this example uses the database scopedb and schema scopedb.public:

scope catalog list databases
scope catalog list schemas --database scopedb
scope catalog list tables --schema scopedb.public

list supports databases, schemas, tables, and views. Use --database to limit schemas, and --database or --schema to limit tables or views.

get, plan, and apply default to the entire catalog. Select one resource with a single scope flag:

Names are fully qualified and bare identifiers are case insensitive. Use backticks for case-sensitive names or special characters, for example --table 'scopedb.public.`Events.Daily`'.

Choose a table from the list and export its definition. If the workspace has no user tables yet, follow the quickstart to create and populate events. The examples below use that table as scopedb.public.events:

scope catalog get --table scopedb.public.events > events.yaml

Review and apply a saved plan

For a first change, edit only the top-level comment in events.yaml, for example comment: Checkout events. Keep the rest of the exported definition, including columns. Preview the change and save a plan:

scope catalog plan --table scopedb.public.events -f events.yaml > plan.yaml

Review the displayed diff, then apply the saved plan and read the definition back to verify the comment:

scope catalog apply --plan plan.yaml
scope catalog get --table scopedb.public.events

A definition replaces the selected resource, so omitted objects or settings may be removed. Plan diffs go to stderr and the saved plan goes to stdout. Applying a saved plan does not prompt again and fails if the connection or catalog has changed; data-loss changes require --allow-destructive. Plans can contain credentials from the exported definition, so protect them like the source file.

Apply a definition directly

For an interactive edit, apply the definition file without saving a separate plan:

scope catalog apply --table scopedb.public.events -f events.yaml

The command previews the diff and asks for confirmation, defaulting to no. Automation requires --yes, plus --allow-destructive when data may be lost. Input definitions can be YAML or JSON; -f - reads stdin, which also requires --yes or a saved plan. Use scope catalog --help and each subcommand's --help for all options.

Remove a resource

Select the resource explicitly:

scope catalog drop --table scopedb.public.events

The command previews the deletion and uses the same confirmation rules as direct apply. In automation, pass both --yes and --allow-destructive when data may be lost. drop --all selects the entire user catalog. Data-loss risks include removing tables or physical columns, shortening retention, and changing deduplication on existing tables.

Timeouts and interrupted writes

Catalog requests have a five-minute limit by default; change it with --request-timeout, or use 0 to disable it. Preview and commit each receive that budget; time spent reviewing a diff does not consume it.

If a saved plan fails because the connection or catalog changed, export the current definition, reapply your intended edit, and generate and review a new plan. A timeout or interrupted connection during commit can leave the outcome unknown. The CLI never automatically retries a Catalog write. Read the catalog before deciding whether to submit another change, including when the CLI reports that a write succeeded but its result could not be printed.