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:
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

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

​
capsule create

Use create to scaffold a production-shaped app from a template.
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:
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:
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:
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 list

​
capsule app get

​
capsule channel

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

​
Common commands

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 fs

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

​
Common commands

​
A smaller workflow

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