# Catalog with the CLI

[Read this page in HTML](https://www.scopedb.io/docs/guides/scopedb-cli/catalog)

Use `scope catalog` after [connecting the CLI](https://www.scopedb.io/docs/guides/scopedb-cli/connect.md). 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`:

```bash
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:

| Resource | Scope                     |
| -------- | ------------------------- |
| Database | `--database DB`           |
| Schema   | `--schema DB.SCHEMA`      |
| Table    | `--table DB.SCHEMA.TABLE` |
| View     | `--view DB.SCHEMA.VIEW`   |

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](https://www.scopedb.io/docs/guides/quickstart.md) to create and populate `events`. The examples below use that table as `scopedb.public.events`:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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.

## Related contents

* [Connect the CLI](https://www.scopedb.io/docs/guides/scopedb-cli/connect.md)

* [Catalog over HTTP](https://www.scopedb.io/docs/api-reference/catalog.md)

* [Automation](https://www.scopedb.io/docs/guides/scopedb-cli/automation.md)