Skip to content
cantelopBeta

CLI reference

Use the CLI to develop, deploy, configure, and operate an App. Start with the quick start for installation, or run cantelop --help for the command overview.

Project#

Project commands read cantelop.json and resolve its App slug. Use -config PATH when the manifest is elsewhere. Paths in the manifest are relative to that file.

For the optional Dockerfile and its build context, see Session runtime configuration.

  • cantelop init -app SLUG -provider openai|claude|pi creates the manifest, API and Session entrypoints, and package file. The provider is required. It needs no login and refuses to overwrite files.
  • cantelop dev serves the App at 127.0.0.1:8787 and rebuilds after edits. -port changes the port, -env-file chooses a local environment file, and --container runs Sessions in Docker. Restart container mode after edits.
  • cantelop build builds the API bundle and Linux runtime image locally. It does not require login or upload anything.
  • cantelop doctor checks the toolchain, project, authentication, and required production configuration. It runs every check and exits non-zero on failure.
  • cantelop deploy builds, uploads, and creates a release. --dry-run stops after the build; --create-app allows creation of a missing App without an interactive prompt.

Operations#

These commands use the App named in the manifest and accept --json. logs --follow --json emits one event per line; finite commands return one document.

  • cantelop logs --follow tails completed-request events with status, duration, Session, and Workspace. Omit --follow for a single read.
  • cantelop session list lists Sessions and their states.
  • cantelop session inspect SESSION_ID shows one Session's details.
  • cantelop session terminate SESSION_ID releases its Sandbox. The Session remains reusable and Workspace files persist.
  • cantelop releases lists releases newest first.
  • cantelop rollback activates the newest superseded release. It refuses to race a deployment still being provisioned.

Resources#

Resource commands take generated App IDs instead of using the project manifest.

  • cantelop app list lists your Apps and their IDs.
  • cantelop app inspect APP_ID shows an App, its Workspaces, and active release.
  • cantelop app create -slug SLUG creates an App at https://<slug>.cantelop.dev.
  • cantelop app archive APP_ID removes the App and its Workspaces from product reads and queues cleanup. Local project files remain untouched.
  • cantelop app env set APP_ID NAME=VALUE sets a variable. Use env list APP_ID to read values and env unset APP_ID NAME to remove one.
  • cantelop app secret set APP_ID NAME reads a secret from stdin. Use secret list APP_ID to list names and secret unset APP_ID NAME to remove one. Values are never returned.
  • cantelop app deploy APP_ID -image IMAGE -artifact DIRECTORY deploys artifacts built by your own automation.

Variables and secrets are shared by the API and newly started Sessions. See environments for local defaults and production checks.

Account#

  • cantelop login opens browser authorization and stores the CLI credential with mode 0600. -console ORIGIN selects another console; CANTELOP_CONFIG overrides the credential file path.
  • cantelop version prints the CLI version and source commit. -v is an alias.
  • cantelop --help shows command groups and common examples. help and -h are aliases.

Uninstall#

Stop any running cantelop dev process first. For a Homebrew installation, run brew uninstall cantelop. For the alternative installer, remove only the cantelop executable in ~/.local/bin, or the custom CANTELOP_INSTALL_DIR you selected. Do not remove the whole directory, which may contain other tools.

If an earlier installer edited your shell profile, remove the line marked # added by cantelop installer from .zshrc, .bashrc, .bash_profile, .profile, or the fish configuration file conf.d/cantelop.fish, as appropriate. Keep any PATH entries needed by your other software.

Uninstalling the CLI does not delete local projects, saved credentials, or hosted Apps and Workspaces. Use cantelop app archive APP_ID before uninstalling if you want to archive a hosted App and queue its cleanup.