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 jsonimport pixeltable as pxtimport subprocessfrom pixeltable.functions.video import frame_iteratordef pxt_json(*args: str) -> object: """Run pxt with --json and parse stdout.""" return json.loads(subprocess.check_output(['pxt', *args], text=True))
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.
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 shellpxt> ls cli_demopxt> count cli_demo/framespxt> 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.
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 initpxt schema update app.py cli_demo # create the tablespxt service update app.py cli_demo # start the services in the backgroundpxt service list # the address, endpoint and pid of each servicecurl -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,thumbpxt service stop videos # take it down again