Interaction with the Shuttle services is mainly done with through the cargo-shuttle Command Line Interface (CLI).

Some tasks, such as viewing logs, can also be done in the Shuttle Console.

Commands are issued in the format: cargo shuttle [OPTIONS] <COMMAND>.

To get an overview of available commands, subcommands, and options, run:

cargo shuttle help
# or
cargo shuttle <COMMAND> --help

Commands

CommandDescription
initGenerate a Shuttle project from a template
runRun a Shuttle service locally
deployDeploy a Shuttle service
deploymentManage deployments of a Shuttle service [aliases: depl]
statusView the status of a Shuttle service
stopStop a Shuttle service
logsView logs of a Shuttle service
projectManage projects on Shuttle [aliases: proj]
resourceManage resources [aliases: res]
cleanRemove cargo build artifacts in the Shuttle environment
loginLogin to the Shuttle platform
logoutLog out of the Shuttle platform
generateGenerate shell completions and man page
feedbackOpen an issue on GitHub and provide feedback
upgradeUpgrade the cargo-shuttle binary
helpPrint this message or the help of the given subcommand(s)

Cookbook / Cheat Sheet

These are some useful sequences of commands that are handy to keep in your back pocket. For full documentation, use --help on the respective command. Use the global --debug flag to print detailed debug output.

Get started

  • cargo install cargo-shuttle: For more alternatives, see Installation.
  • cargo shuttle login: Open the Shuttle Console and paste the API key to log in.
  • cargo shuttle init: Log in and initialize a project.

Local run

  • cargo shuttle run: Run the project locally so you can test your changes. For more tips, see Local Run.
  • cargo shuttle run --port 8080: Change the local port.
  • cargo shuttle run --port 8080 --external: Expose to local network by listening on 0.0.0.0.
  • cargo shuttle run --secrets <file>: Use a non-default secrets file for this run.

Start and deploy a project

  • cargo shuttle project start: Start the container for this project on Shuttle.
  • cargo shuttle deploy: Deploy the project to Shuttle.
  • cargo shuttle deploy --allow-dirty: Deploy regardless whether there are pending git changes. Alias: --ad.
  • cargo shuttle deploy --no-test: Don’t run unit tests before starting the deployment. Alias: --nt.
  • cargo shuttle deploy --secrets <file>: Use a non-default secrets file for this deployment. It must be located in the same folder that Secrets.toml should be in.

Manage projects

All project-related commands can use:

  • --working-directory <path> or --wd <path> to execute the command in a different folder.
  • --name <name> to specify project name explicitly (see Project name).
  • cargo shuttle project list: List your projects.
  • cargo shuttle project status: Check the state of this project.
  • cargo shuttle project restart: Restart your project’s container and upgrade to the latest deployer. See Upgrading.
  • cargo shuttle project delete: Delete a project. The project might need to be restarted first, and all resources need to be deleted first.

Manage deployments and logs

  • cargo shuttle deployment list: List deployments in this project.
  • cargo shuttle status: Show status of the currently running deployment.
  • cargo shuttle stop: Stop the currently running deployment.
  • cargo shuttle logs: Get all logs from the currently running deployment.
  • cargo shuttle logs --latest: Get all logs from the currently running deployment.
  • cargo shuttle logs <id>: Get all logs from a specific deployment.
  • cargo shuttle logs --follow: Stream logs of the deployed service and stream them to your terminal.
  • cargo shuttle logs --raw: Print the logs without timestamps and origin tags. The --raw flag is also available for the run and deploy commands.

Manage resources

  • cargo shuttle resource list: List resources linked to this project.
  • cargo shuttle resource delete <type>: Delete a resource such as databases and secrets.

Shell completions

Use cargo shuttle generate shell <shell> with one of: bash, elvish, fish, powershell, zsh.

Example configuration for Zsh on Linux: add eval "$(cargo shuttle generate shell zsh)" to ~/.zshrc.

Utility

  • cargo shuttle <command> --debug: Turn on tracing output for Shuttle libraries. (WARNING: can print sensitive data)
  • cargo shuttle deploy --output-archive <path>: Dump the deployment archive to disk instead of deploying it. Useful for debugging.