Skip to main content
The capsule CLI is installed with the cpsl package. In day-to-day use, most people end up living in a pretty small subset of commands:
  • capsule create
  • capsule login
  • capsule serve
  • capsule deploy
  • capsule secret
  • capsule fs
That is normal. Most work happens in the loop of logging in, serving locally, creating the resources the app depends on, and deploying.

​
Worked workflow

This is a realistic day-to-day loop for a real app: 
capsule create my-app --template quickstart
cd my-app
uv sync
capsule secret create ANTHROPIC_API_KEY=sk-ant-...
capsule serve app.py:app
capsule deploy app.py:app
That one sequence covers the main platform primitives:
  • project creation from a production-shaped template
  • app-owned secrets
  • local development
  • hosted deployment

​
Top-level commands

capsule --help
Main command groups:
  • create
  • login
  • app
  • channel
  • deploy
  • secret
  • serve
  • fs

​
capsule create

Use create to scaffold a production-shaped app from a template. 
capsule create my-app --template quickstart
capsule create studio --template media-studio
capsule create browser-demo --template browser-agent
capsule create monitor --template background-agent
Templates:
  • quickstart
  • media-studio
  • browser-agent
  • background-agent
The command prints the exact uv sync, capsule secret create, capsule serve, and capsule deploy steps for the chosen template.

​
capsule login

Use login to connect your local machine to a Capsule workspace: 
capsule login
Useful options:
  • --host
  • --port
  • --http-port

​
capsule serve

serve is the local development loop. It uploads the project, boots the runtime, and hot-reloads as you edit: 
capsule serve app.py:app
Options:
  • --channel <name> bind one or more named channels during local serve
  • --force-channel unbind or rebind existing channel bindings
Entry-point format is always file.py:symbol. For example, capsule serve app.py:app means “load the symbol app from app.py”.

​
capsule deploy

When the app looks good locally, deploy promotes that same definition to a hosted version: 
capsule deploy app.py:app
Deploy reads the app definition and sends the runtime image, pages, integrations, schedules, secrets, filesystems, pricing, and source archive to Capsule. If serve is the local development loop, deploy is the same app definition promoted to a hosted version.

​
capsule app

Manage workspace apps. If you mostly work from code, you may not use this group every day. It becomes handy when you need to inspect what already exists in the workspace.

​
capsule app create

capsule app create --name my-app --price 500

​
capsule app list

capsule app list

​
capsule app get

capsule app get <app-id>

​
capsule channel

Use channel to manage named external channel resources that apps can bind to.

​
Common commands

capsule channel create my-tg-bot --type telegram -c bot_token=123:ABC
capsule channel list
capsule channel info my-tg-bot
capsule channel bind my-tg-bot --app my-app
capsule channel unbind my-tg-bot
capsule channel delete my-tg-bot
Supported channel types:
  • telegram
  • slack
  • whatsapp

​
capsule secret

Use secret for app-owned credentials such as model keys, OAuth client secrets, and service tokens.

​
Common commands

capsule secret create OPENAI_API_KEY=sk-...
capsule secret list
capsule secret delete OPENAI_API_KEY

​
capsule fs

Use fs to manage named filesystems that apps can mount at runtime.

​
Common commands

capsule fs create reports
capsule fs list
capsule fs delete reports
capsule fs ls reports /
capsule fs upload reports ./report.csv /incoming/report.csv
capsule fs download reports /incoming/report.csv ./report.csv

​
A smaller workflow

capsule create my-app --template quickstart
cd my-app
uv sync
capsule secret create ANTHROPIC_API_KEY=sk-ant-...
capsule serve app.py:app
capsule deploy app.py:app
If you only remember one thing from this page, make it this: most of the CLI is just helping you move the same app definition from local iteration to a deployed product, while creating the workspace resources that app needs along the way.

​
See also