Getting Started
Command Line Interface
Getting Started
Command Line Interface
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:
Commands
| Command | Description |
|---|---|
| init | Generate a Shuttle project from a template |
| run | Run a Shuttle service locally |
| deploy | Deploy a Shuttle service |
| deployment | Manage deployments of a Shuttle service [aliases: depl] |
| status | View the status of a Shuttle service |
| stop | Stop a Shuttle service |
| logs | View logs of a Shuttle service |
| project | Manage projects on Shuttle [aliases: proj] |
| resource | Manage resources [aliases: res] |
| clean | Remove cargo build artifacts in the Shuttle environment |
| login | Login to the Shuttle platform |
| logout | Log out of the Shuttle platform |
| generate | Generate shell completions and man page |
| feedback | Open an issue on GitHub and provide feedback |
| upgrade | Upgrade the cargo-shuttle binary |
| help | Print 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 on0.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--rawflag is also available for therunanddeploycommands.
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.
Was this page helpful?