CLI Reference

pxt --help
pxt health

pxt <command> [args...]

pxt cd my_dir                      # relative paths now resolve under my_dir
pxt pwd                            # print the current working directory
pxt ls sub                         # lists my_dir/sub
pxt cd ..                          # up one level
pxt cd                             # clear it

# inspect
pxt ls -l                          # everything under root, with metadata
pxt ls some_dir --counts           # row counts (parallelized)
pxt describe my_dir/my_table       # schema
pxt rows my_dir/my_table -n 5      # first 5 stored cells

# query
pxt get my_dir/my_table 42         # PK lookup
pxt count my_dir/my_table          # row count
pxt errors my_dir/my_table         # rows where a computed column failed

# ops
pxt drop my_dir/my_table -f
pxt mv my_dir/my_table other_dir
pxt revert my_dir/my_table --steps 3 -f

# navigate
pxt cd my_dir                      # set the working directory (this terminal)
pxt pwd                            # print it

# declarative schemas
pxt schema diff   schema.py my_app   # what 'update' would change (exit 2 = drift)
pxt schema update schema.py my_app   # create and migrate the declared tables
pxt schema prune  schema.py my_app -f # drop the undeclared ones

# interactive
pxt shell

# serve locally
pxt serve my-service

# cloud — databases
pxt db create pxt://myorg:mydb
pxt db list pxt://myorg
pxt db update-runtime pxt://myorg:mydb

# cloud — services
pxt service create my-service --base-uri pxt://myorg:mydb
pxt service list pxt://myorg:mydb
pxt service status pxt://myorg:mydb/services/my-service

pxt ls                            # root
pxt ls some_dir                   # contents of some_dir
pxt ls -l some_dir                # with metadata
pxt ls --counts                   # with row counts

path                kind   cols  version  flags
agent_demo          dir                       -
audio_chunks        view      9        3  ci
chess_vids          table     3        3  ci
chk                 table     2        1  i

pxt describe my_dir/my_table
pxt describe my_dir/my_table --json

pxt columns                       # every column in the catalog
pxt columns my_dir/my_table       # one table
pxt columns my_dir                # every table under a directory, recursively
pxt columns pxt://org:db          # every table in a hosted database
pxt columns --computed            # computed columns across every table
pxt computed                      # same as above

pxt idxs                          # every index
pxt idxs my_dir/my_table          # indexes on one table
pxt idxs my_dir                   # every table under a directory, recursively
pxt idxs pxt://org:db             # every table in a hosted database
pxt idxs --embedding              # only embedding indexes

pxt history my_dir/my_table
pxt history my_dir/my_table -n 5  # last 5 versions

pxt status
pxt status --sizes --json

pxt config
pxt config --section openai
pxt config --source env

pxt rows my_dir/my_table -n 3
pxt rows my_dir/my_table --cols id,text,score

pxt get my_dir/my_table 42                    # single-column PK, int
pxt get my_dir/my_table some_string_id        # single-column PK, string
pxt get my_dir/my_table 42 abc                # composite PK, in declared order
pxt get my_dir/my_table 42 --cols id,text     # restrict to listed columns

pxt count my_dir/my_table         # prints the integer
pxt count my_dir/my_table --json

pxt errors my_dir/my_table
pxt errors my_dir/my_table --col embedding

pxt drop my_dir/my_table -f                 # drop a table
pxt drop my_dir/my_table --cascade -f       # also drop dependent views
pxt drop my_dir/my_table -n                 # dry-run

pxt drop-dir my_dir -f            # remove an empty directory
pxt drop-dir my_dir -r -f         # recursive: also remove contained tables/subdirs

pxt rename my_dir/old_name new_name

pxt mv my_dir/my_table other_dir              # -> other_dir/my_table
pxt mv my_dir/my_table /                      # move to root

pxt revert my_dir/my_table -f                 # undo the last op
pxt revert my_dir/my_table --steps 3 -f       # roll back 3 versions

pxt schema example --out schema.py

from __future__ import annotations  # required to declare a model on Python 3.14+

import pixeltable as pxt
import pixeltable.functions as pxtf

TableModel = pxt.model_base()

class Docs(TableModel, name='docs'):
    title: pxt.Required[pxt.String]           # a stored column; without Required it is nullable
    body: pxt.String
    title_upper = pxtf.string.upper(title)    # a computed column: an assignment, not an annotation

class Titled(TableModel, name='titled', base=Docs.where(Docs.title != '')):
    headline = Docs.title_upper + '!'         # a view of Docs, filtered by its base= query

pxt schema diff   schema.py my_app     # review
pxt schema update schema.py my_app     # apply

~ my_app/docs              update
    + column 'author' will be added  safe
    - column 'body' will be dropped  DESTRUCTIVE
= my_app/titled_docs       no change
! my_app/scratch           extra (not in schema)

Plan: 0 create, 1 update, 1 unchanged, 1 extra  |  1 destructive

pxt schema update schema.py my_app                          # safe changes
pxt schema update schema.py my_app -n                       # the plan, applying nothing
pxt schema update schema.py my_app --allow-destructive -f   # including drops

pxt schema diff schema.py pxt://acme:main/prod    # 0 = in sync, 2 = drift, 1 = error

{
  "path": "my_app/docs",
  "model_cls": "Docs",
  "kind": "table",
  "exists": true,
  "resolution": "update_destructive",
  "destructive": true,
  "ops": [
    {"target": "column", "name": "author", "op": "add", "severity": "additive", "destructive": false,
     "description": "column 'author' will be added", "details": {"type": "String"}},
    {"target": "column", "name": "body", "op": "drop", "severity": "destructive", "destructive": true,
     "description": "column 'body' will be dropped", "details": {}}
  ]
}

pxt schema prune schema.py my_app -n     # list what would be dropped
pxt schema prune schema.py my_app -f     # drop it

$ pxt shell
pxt> ls
path                kind
agent_demo          dir
chess_vids          table
...
pxt> describe chess_vids
...
pxt> exit

pxt ls --json | jq '.entries[] | select(.kind == "table")'
pxt get my_dir/my_table 42 --json | jq '.row'
pxt count my_dir/my_table --json | jq '.count'

# service.toml
[[pixeltable.service]]
name = "my-service"
port = 8000

[[pixeltable.service.routes]]
type = "insert"
table = "my_dir/my_table"
path = "/generate"
inputs = ["prompt"]
outputs = ["prompt", "result"]

[[pixeltable.service.routes]]
type = "query"
path = "/search"
query = "myapp.queries.search_docs"

pxt serve my-service --config service.toml

pxt serve insert --table my_dir.my_table --path /generate \
  --inputs prompt --outputs prompt result --port 8000

pxt serve query --query myapp.queries.search_docs --path /search

{"status": "started", "host": "0.0.0.0", "port": 8000, "url": "http://localhost:8000", "docs_url": "http://localhost:8000/docs", "routes": 2}

{"status": "error", "code": "EADDRINUSE", "port": 8000, "message": "port 8000 is already in use"}

pxt serve my-service --config service.toml --dry-run --json

pxt serve insert --table my_dir.my_table --path /generate \
  --inputs prompt --outputs prompt result --port 8000

curl -X POST http://localhost:8000/generate \
  -H 'Content-Type: application/json' \
  -d '{"prompt": "a sunset over the ocean"}'

pxt serve update --table my_dir.my_table --path /update \
  --inputs prompt --outputs id prompt result

pxt serve delete --table my_dir.my_table --path /delete

pxt serve query --query myapp.queries.search_docs --path /search

pxt serve query --query myapp.queries.lookup_by_id --path /lookup \
  --one-row --method get

pxt serve insert --table my_dir.my_table --path /generate \
  --inputs prompt --outputs prompt result \
  --export-sql-db-connect 'postgresql+psycopg://user:pw@host/analytics' \
  --export-sql-table generations

pxt serve my-service --config service.toml --dry-run

pxt serve my-service --config service.toml --port 9000

pxt serve insert --table my_dir.images --path /resize \
  --inputs width height --uploadfile-inputs image \
  --outputs resized --return-fileresponse

curl -X POST http://localhost:8000/resize \
  -F [email protected] -F width=640 -F height=480 \
  --output resized.jpg

pxt serve insert --table my_dir.videos --path /ingest --background

{"id": "abc123", "job_url": "http://localhost:8000/jobs/abc123"}

[pixeltable.database]
# Include/exclude patterns for project files bundled into the runtime image.
# Glob patterns relative to the project root.
include = ["app/**", "models/**"]
exclude = ["__pycache__", "*.pyc", ".git", ".env", "*.egg-info", ".venv"]

# Optional: build Pixeltable itself from source instead of the published PyPI release.
# Use this to deploy changes from a feature branch before they are released.
[pixeltable.database.pixeltable_source]
git    = "https://github.com/pixeltable/pixeltable.git"
branch = "my-feature-branch"
# rev  = "abc1234"  # pin to a specific commit or tag instead of branch HEAD

[[pixeltable.service]]
name    = "my-service"
modules = ["app"]        # Python modules imported at service startup

# INSERT / COMPUTE — append a row, trigger computed columns, return outputs
[[pixeltable.service.routes]]
type    = "insert"       # "compute" is an alias for "insert"
path    = "/ingest"
table   = "my_schema/documents"
inputs  = ["text", "title"]
outputs = ["text", "summary", "embedding"]

# FILE UPLOAD — accept multipart/form-data, return a file or JSON
[[pixeltable.service.routes]]
type              = "compute"
path              = "/image"
table             = "my_schema/images"
uploadfile_inputs = ["image"]
outputs           = ["description"]
background        = true           # returns job_url immediately; poll for result

# QUERY — call a @pxt.query function
[[pixeltable.service.routes]]
type   = "query"
path   = "/search"
query  = "app:search_docs"         # module:attr path to a @pxt.query function
inputs = ["query_text", "limit"]
method = "post"                    # "get" or "post" (default: "post")

# UPDATE — mutate existing rows by primary key
[[pixeltable.service.routes]]
type    = "update"
path    = "/update"
table   = "my_schema/documents"
inputs  = ["id", "text"]
outputs = ["text", "summary"]

# DELETE — remove rows matching specified columns
[[pixeltable.service.routes]]
type          = "delete"
path          = "/delete"
table         = "my_schema/documents"
match_columns = ["id"]

pxt db create pxt://myorg:mydb
pxt db create pxt://myorg:mydb --location aws --region us-east-1

pxt db list pxt://myorg
pxt db list pxt://myorg --json

pxt db status pxt://myorg:mydb

pxt db start pxt://myorg:mydb

pxt db stop pxt://myorg:mydb

pxt db update pxt://myorg:mydb --workers 2
pxt db update pxt://myorg:mydb --cpu 1 --memory 2048 --disk 20

pxt db update-runtime pxt://myorg:mydb

pxt db delete pxt://myorg:mydb --json

pxt service create my-service --base-uri pxt://myorg:mydb
pxt service create my-service --base-uri pxt://myorg:mydb --workers 2

pxt service list pxt://myorg:mydb

pxt service status pxt://myorg:mydb/services/my-service

pxt service start pxt://myorg:mydb/services/my-service

pxt service stop pxt://myorg:mydb/services/my-service

pxt service update pxt://myorg:mydb/services/my-service --workers 2

pxt service delete pxt://myorg:mydb/services/my-service

pxt org list
pxt org list --json

pxt org status pxt://myorg