Operate Your AI Catalog from the Terminal: Introducing the Pixeltable CLI

Summary: Pixeltable 0.6.5 shipped a first-class pxt CLI for catalog operations. Define your schema and computed columns in Python once; then use the terminal to list tables, peek at rows, inspect failed computed cells, roll back versions, and emit machine-readable JSON for agents. Serving is now one app.py: TableModel plus FastAPIRouter, applied with pxt schema update and served locally with pxt service update. A local daemon keeps commands fast (~40 ms after the first invocation), and --json output makes the CLI a stable interface for automation and AI assistants.

You Defined the Pipeline in Python. Now What?#

Most Pixeltable projects follow a familiar pattern: you create tables and views, attach computed columns for embeddings or LLM calls, add embedding indexes, and wire up @pxt.query functions for retrieval. That declarative Python layer is where the hard design work happens.

Then day-two operations begin. You need to answer questions like:

• Did the new documents get chunked and embedded?
• Which rows failed on the vision column—and why?
• What changed between yesterday's schema and today's?
• Can I expose this table as an HTTP endpoint without writing FastAPI boilerplate?

Jumping back into a REPL or building a one-off admin dashboard for every project does not scale—especially when AI agents and coding assistants need stable, machine-readable ways to inspect your catalog.

The pxt CLI closes that gap. It ships with the pixeltable package and covers two surfaces:

• Catalog operations — inspect, query, mutate, and version tables, views, and directories
• Service deployment — declare FastAPIRouter routes in app.py, then pxt service update against a local dir or pxt://. pxt service run is local only

Full reference: CLI documentation. Step-by-step cookbook: Working with the Pixeltable CLI.

Fast by Design: The Catalog Daemon#

On the first catalog command, pxt auto-starts a long-lived local daemon bound to 127.0.0.1:22089 (override with PXT_PORT). The daemon survives across shell sessions, so subsequent commands avoid repeated Python startup—typically ~40 ms per call after the warm-up.

pxt health always returns JSON with version, PID, and configured paths. For runtime stats (table count, error count, media directories), use pxt status.

For HTTP serving, install the optional extra:

Example 1: Inspect the Catalog#

Suppose you have a video pipeline with a table and a frame view. In Python you might define:

From the terminal, explore without writing more Python:

Sample pxt ls -l output:

This is the fastest way to verify that your computed column graph materialized as expected after an insert or schema change.

Example 2: Query Rows and Debug Failures#

Catalog query commands read stored cells. Unstored computed columns are skipped by default—pass them explicitly with --cols when you want to force evaluation (which may invoke LLMs or expensive compute).

When a stored computed column fails, Pixeltable records the error on the row. Find every failure from the terminal:

This is invaluable in production: partial API failures do not corrupt your table, and pxt errors gives you the primary keys to retry exactly where things broke—a pattern we covered in rate limiting and graceful failure handling.

Example 3: Version History and Revert#

Every insert and schema change creates a new table version. Pixeltable's time travel and versioning are not just Python APIs—you can inspect and roll back from the CLI.

Destructive mutations (drop, rm, revert) prompt [y/N] in interactive terminals. In CI or agent scripts, pass -f to skip confirmation. Use -n / --dry-run to preview mutations without executing them.

Example 4: Agent-Friendly Scripting with --json#

Most inspection, query, and mutation commands accept --json for stable, machine-readable output. That makes the CLI a natural companion to the Pixeltable MCP server and other agent harnesses: Python defines the pipeline; agents operate the catalog through predictable JSON.

In Python scripts, shell out once and parse:

For many commands in one session, pxt shell keeps the daemon warm and errors from one command do not kill the REPL:

Check configuration and credentials (values show as <redacted> when set):

Example 5: HTTP Endpoints From the Same File#

Declare FastAPIRouter routes in app.py next to the tables. pxt schema update creates the catalog; pxt service update starts local HTTP with OpenAPI docs at /docs. Preview the service plan without starting a process:

Then serve and call an insert route:

Same file on Cloud: pxt db update pxt://org:db, then pxt schema update app.py pxt://org:db, then pxt service update app.py pxt://org:db. pxt service run is local only. See the HTTP Serving guide and our application templates for agents.

Command Map at a Glance#

Category	Commands	Typical use
Inspection	ls, describe, columns, computed, idxs, history, status, config	Schema discovery, index audit, config check
Query	rows, get, count, errors	Peek at data, PK lookup, failure triage
Mutation	drop, rm, rename, mv, revert	Catalog housekeeping, rollbacks
Interactive	shell	Multi-step exploration sessions
Serving	service, schema	Local HTTP from app.py; hosted tables via pxt schema update
Lifecycle	daemon, dashboard, health	Daemon control, browser UI, health probe

Universal flags worth memorizing: --json (machine output), -f (skip confirmation on destructive ops), -n / --dry-run (preview mutations on schema and service update/prune).

Where the CLI Fits in Your Stack#

The CLI does not replace the Python SDK—it operationalizes it.

• Python SDK — define tables, views, computed columns, and queries (schema-driven infrastructure)
• pxt CLI — inspect, debug, script, and serve that catalog from the terminal
• MCP server — expose the same operations to Claude, Cursor, and other agents conversationally
• Pixeltable Cloud — managed org/database/dashboard layer for teams (organization and collaboration)

If you are building agents whose session state must be durable and queryable, pair the CLI's inspection commands with the patterns in agents as data: the session log as system of record—define the log in Python, operate and debug it from pxt.

FAQ#

Do I need a separate install for the CLI?#

No. pxt ships with pip install pixeltable. HTTP serving requires pip install 'pixeltable[serve]'.

Why is there a daemon?#

Catalog commands talk to a local daemon so each invocation stays fast (~40 ms after warm-up) instead of paying Python import and catalog connect costs on every call.

Which commands support --json?#

Inspection, query, and mutation catalog commands, plus the schema and service verbs, db, org, and daemon status. Exceptions: shell (interactive), health (always JSON), and dashboard (opens a URL).

How is pxt service different from FastAPIRouter in Python?#

They are the same contract. FastAPIRouter in app.py declares the routes; pxt service update runs that file against a local catalog or a pxt:// database. pxt service run is local only. See the serving guide.

Can AI agents use the CLI directly?#

Yes. Stable --json output is designed for scripting and agent workflows. For conversational access, the Pixeltable MCP server wraps catalog operations for Claude and Cursor; the CLI is the same surface in terminal form.

Get Started#

1. pip install -U 'pixeltable[serve]'
2. Define a table or view in Python (or use an existing catalog)
3. Run pxt ls -l and pxt describe your_table
4. Scaffold with pxt service example --out app.py, then pxt schema update and pxt service update
5. Read the CLI reference and the Working with the CLI cookbook

Define once in Python. Operate everywhere from the terminal.