CocoIndex CLI

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

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 flow definitions are located.

APP_TARGET Format

The APP_TARGET can be:

1. An Python module name that contains your flow definitions (e.g., main, my_package.flows). 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 flows (e.g., main.py, path/to/my_flows.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 flow (like show, update, evaluate), you can combine the application reference with a flow name:

   • my_package.flows:MyFlow
   • path/to/my_flows.py:MyFlow

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:

  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:

Option	Description
-f, --force	Skip confirmation prompt.
--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:

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:

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.

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

Usage:

cocoindex show [OPTIONS] APP_TARGET

Options:

Option	Description
--help	Show this message and exit.

---

update

Run a v1 app once (one-time update).

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

Usage:

cocoindex update [OPTIONS] APP_TARGET

Options:

Option	Description
--help	Show this message and exit.

---