Gemini CLI + Pixeltable
Google's open-source terminal agent powered by Gemini. Give it a multimodal backend: one app.py declares tables, computed columns, indexes, and HTTP routes.
What is Gemini CLI?
Gemini CLI is Google's open-source agent for the terminal. It reads and writes files, runs shell commands, and supports MCP servers through ~/.gemini/settings.json, including remote servers via the mcp-remote bridge.
Quick start
Four steps. The agent can run all of them when you hand it the setup playbook.
- 01
Install Gemini CLI
Requires Node 20+. Sign in with a Google account for the free tier.
bashnpm install -g @google/gemini-cli gemini
- 02
Install Pixeltable
Python 3.11+ required. `pxt init` marks the project root; schema and service commands refuse an app without one.
bashpip install -U 'pixeltable[serve]' pxt init
- 03
Add the Pixeltable Skill
The Skill teaches the agent table/schema patterns, provider integrations, and anti-patterns. Skip this step if the full Pixeltable plugin is already installed. Source: https://github.com/pixeltable/pixeltable-skill
bashnpx skills add pixeltable/pixeltable-skill npx skills list
- 04
Ship a first app
Declare the tables, start the HTTP routes, then try them in the dashboard. For Cloud, the agent runs `pxt new` for a free database with no account and gives you its claim link, or runs `pxt login` for your account while you confirm its code. Then `pxt db update pxt://<org>:main --add-config-entry`, `pxt schema update`, and `pxt service update`, in that order. The flag writes the hosted entry. An API key is optional for CLI automation.
bashpxt service example --out app.py pxt schema update app.py my_app pxt service update app.py my_app pxt dashboard
MCP configuration
Pixeltable has three MCP servers. Connect the one the job needs.
| Server | Transport | What it can do |
|---|---|---|
| pixeltable-web | HTTP | Read-only docs search and integration listing. No table mutations. |
| pixeltable-cloud | HTTP + AuthKit | Read and operate the signed-in Cloud organization: databases, services, catalog, schemas, bounded table rows, failed cells, and logs. Starts a database or a service at once; stops or restarts either, or sets a secret, after a preview (confirm: true). ?read_only=true leaves only the read tools. |
| pixeltable-developer | stdio | Inspect schemas, query tables, run a REPL against a local or Cloud catalog. |
Connect Pixeltable Cloud (read and operate, AuthKit sign-in)
Optional, for Pixeltable Cloud users. Merge this into `~/.gemini/settings.json`. When Gemini CLI starts the server, the mcp-remote bridge opens the AuthKit sign-in in your browser and keeps the tokens in `~/.mcp-auth`. Read-only mode and disconnecting are on /developers/mcp-cloud.
{
"mcpServers": {
"pixeltable-cloud": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://www.pixeltable.com/mcp/cloud"
]
}
}
}Connect the WebMCP (docs search, no auth)
Gemini CLI reaches remote MCP servers through the mcp-remote bridge. Merge this into `~/.gemini/settings.json`:
{
"mcpServers": {
"pixeltable-web": {
"command": "npx",
"args": [
"mcp-remote",
"https://www.pixeltable.com/mcp"
]
}
}
}Connect the developer MCP (tables + REPL)
Install the server once per machine (step below), then merge this entry into the same file, keeping the entries already there:
{
"mcpServers": {
"pixeltable-developer": {
"command": "mcp-server-pixeltable-developer"
}
}
}Install the developer MCP server
Stdio server that inspects schemas, queries tables, and runs a REPL against a local or Cloud catalog. Repository: https://github.com/pixeltable/mcp-server-pixeltable-developer
uv tool install mcp-server-pixeltable-developer # if uv is missing: # curl -LsSf https://astral.sh/uv/install.sh | sh
Example prompts
What to ask Gemini CLI once Pixeltable is set up.
Install Pixeltable and set up a table that embeds every image I insert.
Build a RAG pipeline over the PDFs in ./docs and expose a FastAPI route that answers questions.
Transcribe every video in ./media with Whisper, index the transcript, and serve semantic search over HTTP.
Add a computed column that captions each uploaded image with a vision model.
Scaffold app.py with pxt service example, declare the schema, and start the service.
Take app.py and deploy it to my Pixeltable Cloud database pxt://myorg:main.
Build a background-remover API: image in, background removed, POST endpoint.
Common workflows
Set up a Pixeltable app
- 1.Hand the agent https://www.pixeltable.com/get-started.md and let it run the playbook
- 2.It installs the pxt CLI and the Pixeltable Skill
- 3.It scaffolds app.py, declares the schema, starts the service
- 4.It verifies the endpoint with a curl request
Build a multimodal pipeline
- 1.Describe the pipeline: ingest media, run models, index results
- 2.The agent declares the table and computed columns in app.py
- 3.It adds an embedding index and an HTTP route that serves results
- 4.Insert a row; computed columns run and indexes stay current
Deploy to Pixeltable Cloud
- 1.Ask the agent to deploy app.py to Cloud
- 2.With no account, the agent runs pxt new and sends you a claim link; with one, it runs pxt login and you confirm the code
- 3.It uses the organization’s main database or the database you specify
- 4.It runs pxt db update, pxt schema update, pxt service update in order
- 5.It finds the hosted endpoint with pxt service list; direct HTTP calls use an API key
Inspect a catalog over MCP
- 1.Connect the pixeltable-developer MCP server
- 2.The agent lists tables and views in the catalog
- 3.It runs read queries and reports schema and row counts
- 4.Keep human confirmation on: the developer server can change local catalog state
Tips for success
Troubleshooting
The Pixeltable Skill is not visible after install
Reload or restart the agent. Confirm the install path with `npx skills list` and that the skill targets the current agent.
The agent does not list the MCP server
Validate the config file JSON. pixeltable-web is a remote HTTP server at https://www.pixeltable.com/mcp; pixeltable-cloud is an AuthKit-protected remote server at https://www.pixeltable.com/mcp/cloud; pixeltable-developer is a stdio command, `mcp-server-pixeltable-developer`. Verify the local server is installed with `mcp-server-pixeltable-developer --help`.
`pxt service check` fails: modifies catalog while imported
app.py must declare TableModel tables and FastAPIRouter routes, not run pxt.create_table() at import. Scaffold with `pxt service example`.
Cloud deploy fails with 404: UDF not found
Order is required: `pxt db update pxt://myorg:main`, then `pxt schema update app.py pxt://myorg:main`, then `pxt service update app.py pxt://myorg:main`. Replace `myorg` with your organization slug.
Frequently asked questions
Can Gemini CLI set up Pixeltable on its own?
Which Pixeltable MCP server should I connect?
Can Gemini CLI deploy to Pixeltable Cloud?
Does the Pixeltable Skill work with Gemini CLI?
Related agents
Give Gemini CLI a multimodal backend
One app.py declares tables, computed columns, indexes, and HTTP routes. Insert a row; the pipeline runs.