Working with the Pixeltable CLI

This documentation page is also available as an interactive notebook. You can launch the notebook in Kaggle or Colab, or download it for use with an IDE or local Jupyter installation, by clicking one of the above links.

Problem

You defined a multimodal pipeline in Python and now need to inspect tables, debug computed columns, roll back changes, and expose HTTP endpoints without writing more application code. Jumping into a REPL or building a custom admin UI for every project does not scale, especially when AI agents need stable, machine-readable output.

Solution

What’s in this recipe:

Inspect catalogs with pxt ls, describe, columns, and idxs
Query and debug rows with pxt rows, count, get, and errors
Manage versions with pxt history and pxt revert
Script and automate with --json, -f, and pxt shell
Validate declarative HTTP serving with pxt serve --dry-run

The pxt CLI ships with Pixeltable (v0.6.5+). Catalog commands talk to a local daemon (~40 ms per call after the first invocation). Use Python to define schema once, then operate the catalog from the terminal. See the CLI reference for every flag.

Setup

%pip install -qU 'pixeltable[serve]'

import json
import pixeltable as pxt
import subprocess
from pixeltable.functions.video import frame_iterator


def pxt_json(*args: str) -> object:
    """Run pxt with --json and parse stdout."""
    return json.loads(subprocess.check_output(['pxt', *args], text=True))

SAMPLE_VIDEO = 'https://raw.githubusercontent.com/pixeltable/pixeltable/release/docs/resources/bangkok.mp4'

pxt.drop_dir('cli_demo', force=True)
pxt.create_dir('cli_demo')

videos = pxt.create_table(
    'cli_demo/videos', {'video': pxt.Video, 'title': pxt.String}
)
frames = pxt.create_view(
    'cli_demo/frames',
    videos,
    iterator=frame_iterator(videos.video, fps=1),
)
frames.add_computed_column(thumb=frames.frame.thumbnail((320, 180)))

videos.insert([{'video': SAMPLE_VIDEO, 'title': 'Bangkok'}])

Step 1: Inspect the catalog

List directories and tables, then drill into schema and computed columns. Flag letters in pxt ls -l: c = computed column, i = index.

!pxt ls -l cli_demo
!pxt describe cli_demo/videos
!pxt columns cli_demo/frames --computed
!pxt idxs cli_demo/frames

Step 2: Query rows

Peek at stored data from the terminal. Pass computed columns explicitly with --cols; unstored computed columns are skipped by default. Thumbnails may take a moment to compute after insert.

!pxt count cli_demo/frames
!pxt rows cli_demo/frames -n 1 --cols pos,thumb

Step 3: Debug computed-column failures

When a stored computed column fails, pxt errors lists the failing rows by primary key.

@pxt.udf
def boom_if_zero(x: int) -> int:
    if x == 0:
        raise ValueError('boom')
    return x


failures = pxt.create_table(
    'cli_demo/failures', {'k': pxt.Required[pxt.Int]}, primary_key='k'
)
failures.add_computed_column(
    result=boom_if_zero(failures.k), on_error='ignore'
)
failures.insert([{'k': 0}, {'k': 1}], on_error='ignore')

!pxt errors cli_demo/failures

Step 4: Version control

Every insert and schema change creates a new table version. Inspect the timeline, then roll back if needed. See Track changes and revert for the Python API.

videos.add_computed_column(label=videos.title.upper())

!pxt history cli_demo/videos -n 5
!pxt revert cli_demo/videos -f
!pxt history cli_demo/videos -n 3

Step 5: Agent-friendly scripting

Most catalog commands accept --json for stable, machine-readable output. Use -f to skip confirmation prompts in non-interactive contexts. For many commands in one session, pxt shell keeps the daemon warm:

pxt shell
pxt> ls cli_demo
pxt> count cli_demo/frames
pxt> exit

tables = [
    e['path']
    for e in pxt_json('ls', 'cli_demo', '--json')['entries']
    if e['kind'] == 'table'
]
print('tables:', tables)
print(
    'frame count:',
    pxt_json('count', 'cli_demo/frames', '--json')['count'],
)

Step 6: Config and health

Check daemon health, runtime status, and resolved configuration (API keys show as <redacted> when set). See Configure API keys for credential setup.

!pxt health
!pxt status
!pxt config --section openai

Step 7: Serve without application code

Validate an insert endpoint with --dry-run --json (no server started). For production, declare routes in pyproject.toml — see HTTP Serving. Full live flow:

pxt serve insert --table cli_demo/videos --path /videos --inputs video title --outputs title
curl -X POST localhost:8000/videos -H 'Content-Type: application/json' \
  -d '{"video": "https://raw.githubusercontent.com/pixeltable/pixeltable/release/docs/resources/bangkok.mp4", "title": "Bangkok"}'
pxt rows cli_demo/frames -n 1 --cols pos,thumb

!pxt serve insert --table cli_demo/videos --path /videos --inputs video title --outputs title --dry-run --json

Next steps

CLI reference: every command and flag
Dashboard: browse tables and preview media in the browser
HTTP Serving: production TOML and FastAPIRouter
Building with LLMs: agent skills, MCP, and pxt --json workflows

Welcome to Pixeltable

Tools

Core Concepts

How-To

Problem

Solution

Setup

Step 1: Inspect the catalog

Step 2: Query rows

Step 3: Debug computed-column failures

Step 4: Version control

Step 5: Agent-friendly scripting

Step 6: Config and health

Step 7: Serve without application code

Next steps

​Problem

​Solution

​Setup

​Step 1: Inspect the catalog

​Step 2: Query rows

​Step 3: Debug computed-column failures

​Step 4: Version control

​Step 5: Agent-friendly scripting

​Step 6: Config and health

​Step 7: Serve without application code

​Next steps

Problem

Solution

Setup

Step 1: Inspect the catalog

Step 2: Query rows

Step 3: Debug computed-column failures

Step 4: Version control

Step 5: Agent-friendly scripting

Step 6: Config and health

Step 7: Serve without application code

Next steps