The CLI reference

Reference for the `cocoindex` CLI — app target formats, environment variable loading, and subcommands for init, ls, show, update (catch-up or live), and drop.

Version

v 1.0.0-alpha48

Last reviewed

Apr 19, 2026

CocoIndex CLI is a standalone tool for easily managing and inspecting your apps.

Invoke the CLI

Once CocoIndex is installed, you can invoke the CLI directly using the cocoindex command. Most commands require an APP_TARGET argument, which tells the CLI where your app definitions are located.

APP_TARGET Format

The APP_TARGET can be:

1. A Python module name that contains your app definitions (e.g., main, my_package.apps). You can also use --app-dir <path> to specify the base directory to load the module from.

2. A path to a Python file defining your apps (e.g., main.py, path/to/my_apps.py).

   The file will be loaded as a top-level Python module, e.g. relative imports will not work as its parent package is not defined (similar to how python main.py resolves imports).

3. For commands that operate on a specific app (like show, update), you can combine the application reference with an app name:

   • my_package.apps:MyApp
   • path/to/my_apps.py:MyApp

Environment Variables

You can set environment variables in an environment file.

• By default, the cocoindex CLI searches upward from the current directory for a .env file.

• You can use --env-file <path> to specify one explicitly:

  Copysh

  cocoindex --env-file path/to/custom.env <COMMAND> ...

Loaded variables do NOT override existing system ones. If no file is found, only existing system environment variables are used.

Global Options

CocoIndex CLI supports the following global options:

• -e, --env-file <path>: Load environment variables from a specified .env file. If not provided, .env in the current directory is loaded if it exists.
• -d, --app-dir <path>: Load apps from the specified directory. It will be treated as part of PYTHONPATH. Default to the current directory.
• -V, --version: Show the CocoIndex version and exit.
• --help: Show the main help message and exit.

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:

cocoindex drop [OPTIONS] APP_TARGET

Options:

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:

cocoindex init [OPTIONS] [PROJECT_NAME]

Options:

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:

cocoindex ls [OPTIONS] [APP_TARGET]

Options:

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:

cocoindex show [OPTIONS] [APP_TARGET]

Options:

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:

cocoindex update [OPTIONS] APP_TARGET

Options: