---
title: CLI *subcommands* reference
description: >
  Reference for every `cocoindex` CLI subcommand — drop, init, ls, show, and
  update (catch-up or live) — with their arguments, flags, and app-target formats.
---
## Subcommands reference

### `drop`

Drop an app and all its target states.

This will:

- Revert all target states created by the app (e.g., drop tables, delete rows)
- Clear the app's internal state database

`APP_TARGET`: `path/to/app.py`, `module`, `path/to/app.py:app_name`, or
`module:app_name`.


**Usage:**

```bash
cocoindex drop [OPTIONS] APP_TARGET
```

**Options:**

| Option | Description |
|--------|-------------|
| `-f, --force` | Skip confirmation prompt. |
| `-q, --quiet` | Avoid printing anything to the standard output, e.g. statistics. |
| `--help` | Show this message and exit. |

---

### `init`

Initialize a new CocoIndex project.

Creates a new project directory with starter files: 1. main.py (Main
application file) 2. pyproject.toml (Project metadata and dependencies) 3.
README.md (Quick start guide)

`PROJECT_NAME`: Name of the project (defaults to current directory name if
not specified).


**Usage:**

```bash
cocoindex init [OPTIONS] [PROJECT_NAME]
```

**Options:**

| Option | Description |
|--------|-------------|
| `--dir DIRECTORY` | Directory to create the project in. |
| `--help` | Show this message and exit. |

---

### `ls`

List all apps.

If `APP_TARGET` (`path/to/app.py` or `module`) is provided, lists apps
defined in that module and their persisted status, grouped by environment.

If `APP_TARGET` is omitted and `--db` is provided, lists all apps from the
specified database.


**Usage:**

```bash
cocoindex ls [OPTIONS] [APP_TARGET]
```

**Options:**

| Option | Description |
|--------|-------------|
| `--db TEXT` | Path to database to list apps from (only used when APP_TARGET is not specified). |
| `--help` | Show this message and exit. |

---

### `show`

Show the app's stable paths.

If `APP_TARGET` is provided, loads the app from the module.
Otherwise, `--db` and `--app-name` can be used to inspect an app
directly from its database without loading the module.


**Usage:**

```bash
cocoindex show [OPTIONS] [APP_TARGET]
```

**Options:**

| Option | Description |
|--------|-------------|
| `--db TEXT` | Path to database (used with --app-name when APP_TARGET is not specified). |
| `--app-name TEXT` | App name to inspect (used with --db when APP_TARGET is not specified). |
| `--tree` | Display stable paths as a tree with component annotations. |
| `--help` | Show this message and exit. |

---

### `update`

Run an app in catch-up mode. With --live, run in live mode.

`APP_TARGET`: `path/to/app.py`, `module`, `path/to/app.py:app_name`, or
`module:app_name`.


**Usage:**

```bash
cocoindex update [OPTIONS] APP_TARGET
```

**Options:**

| Option | Description |
|--------|-------------|
| `-f, --force` | Skip confirmation prompt. |
| `-q, --quiet` | Avoid printing anything to the standard output, e.g. statistics. |
| `--reset` | Drop existing setup before updating (equivalent to running 'cocoindex drop' first). |
| `--full-reprocess` | Reprocess everything and invalidate existing caches. |
| `-L, --live` | Run in live mode (live components continue processing after initial update). |
| `--help` | Show this message and exit. |

---
