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 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 login
capsule secret create OPENAI_API_KEY=sk-...
capsule fs create support-ops
capsule channel create support-telegram --type telegram -c bot_token=123:ABC
capsule serve app:app --channel support-telegram
capsule deploy app:app
That one sequence covers the main platform primitives:
  • workspace authentication
  • app-owned secrets
  • mounted storage
  • external channel resources
  • local development
  • hosted deployment

​
Top-level commands

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

​
capsule bootstrap

Use bootstrap when you want a starting point instead of an empty file. 
capsule bootstrap my-app
capsule bootstrap my-app --template minimal
Templates:
  • chatbot
  • dashboard
  • minimal

​
capsule login

Use login to connect your local machine to a Capsule workspace: 
capsule login
Useful options:
  • --host
  • --port
  • --http-port
If you are targeting a local gateway, set CAPSULE_GATEWAY_URL=localhost:1980 before capsule login.

​
capsule serve

serve is the local development loop. It uploads the project, boots the runtime, and hot-reloads as you edit: 
capsule serve app: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 module:symbol. For example, capsule serve app: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: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 internal 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 login
capsule bootstrap my-app
cd my-app
capsule serve app:app
capsule secret create OPENAI_API_KEY=sk-...
capsule deploy app: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