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
Write tables and routes in app.py. pxt schema update creates the tables; pxt service diff / update starts HTTP

The pxt CLI ships with Pixeltable (v0.7.4+). Catalog commands talk to a local daemon (~40 ms per call after the first invocation). Write tables in Python, then inspect and serve them 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.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 writing a web app

Write tables and routes in app.py. pxt schema update creates the tables. pxt service example writes a starting file; pxt service diff reports what serving it would change, without starting anything. See HTTP Serving. Full live flow. Use pxt service list for the URL; do not hard-code a port:

pxt init
pxt schema update app.py cli_demo           # create the tables
pxt service update app.py cli_demo          # start the services in the background
pxt service list                            # the address, endpoint and pid of each service
curl -X POST http://127.0.0.1:<port>/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 service stop videos                     # take it down again

!pxt service example | head -20

Next steps

CLI reference: every command and flag
Dashboard: browse tables and preview media in the browser
HTTP Serving: FastAPIRouter routes
AI coding agents: agent skills, MCP, and pxt --json workflows

Use Cases

Topics

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 writing a web app

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 writing a web app

​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 writing a web app

Next steps