> For the complete documentation index, see [llms.txt](https://shuttle-1.gitbook.io/shuttle-cobra/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://shuttle-1.gitbook.io/shuttle-cobra/reference/cli-reference.md). # CLI Reference ### Overview The Shuttle CLI for Python is your primary interface for developing, deploying, and managing applications on the Shuttle platform. This reference provides comprehensive documentation for all commands and options. ### Installation It is recommended to use `uv` for dependency management and running the Shuttle CLI. ```bash uv venv source .venv/bin/activate uv add shuttle-cobra ``` Once installed, you can invoke the Shuttle CLI using `uv run -m shuttle`. If your virtual environment is activated, you can also run commands directly using `shuttle`. For example: ```bash uv run -m shuttle deploy # OR shuttle deploy ``` ### Global Options These options are common to many command-line interfaces and may be supported by the underlying Python `click` framework, but are not explicitly defined or handled by the `shuttle` Python application's `__main__.py` for all cases. | Option | Description | | --------- | -------------------------------------------------------------------------------- | | `--debug` | Turn on tracing output for Shuttle libraries (WARNING: can print sensitive data) | ### Commands Reference #### Project Management #### Deployment **`shuttle deploy`** Provision, build, and deploy the application. ```bash uv run -m shuttle deploy [PATH] # OR shuttle deploy [PATH] ``` **Arguments:** * `[PATH]` - The path to your Shuttle project's root directory (defaults to current directory). **Examples:** ```bash uv run -m shuttle deploy # Deploy the project in the current directory shuttle deploy # Deploy the project in the current directory uv run -m shuttle deploy my-project # Deploy a project located in 'my-project' directory shuttle deploy my-project # Deploy a project located in 'my-project' directory ``` **`shuttle destroy`** Destroy the deployed stack and all associated resources for a project. ```bash uv run -m shuttle destroy [PATH] # OR shuttle destroy [PATH] ``` **Arguments:** * `[PATH]` - The path to your Shuttle project's root directory (defaults to current directory). **Examples:** ```bash uv run -m shuttle destroy # Destroy the project in the current directory shuttle destroy # Destroy the project in the current directory uv run -m shuttle destroy my-project # Destroy a project located in 'my-project' directory shuttle destroy my-project # Destroy a project located in 'my-project' directory ``` #### Local Development **`shuttle run`** Run your Shuttle project locally. ```bash uv run -m shuttle run [PATH] # OR shuttle run [PATH] ``` **Arguments:** * `[PATH]` - The path to your Shuttle project's root directory (defaults to current directory). **Examples:** ```bash uv run -m shuttle run # Run the project in the current directory locally shuttle run # Run the project in the current directory locally uv run -m shuttle run my-project # Run a project located in 'my-project' directory locally shuttle run my-project # Run a project located in 'my-project' directory locally ``` #### Logs **`shuttle logs`** Show logs from the deployed application. ```bash uv run -m shuttle logs [PATH] # OR shuttle logs [PATH] ``` **Arguments:** * `[PATH]` - The path to your Shuttle project's root directory (defaults to current directory). **Examples:** ```bash uv run -m shuttle logs # View logs for the project in the current directory shuttle logs # View logs for the project in the current directory uv run -m shuttle logs my-project # View logs for a project located in 'my-project' directory shuttle logs my-project # View logs for a project located in 'my-project' directory ``` ### Environment Variables The Shuttle Cobra CLI primarily relies on AWS authentication configured in your environment. | Variable | Description | | ----------------------- | ----------------------------------------------------------------------------------------- | | `AWS_ACCESS_KEY_ID` | Your AWS access key ID. Used for programmatic access to AWS. | | `AWS_SECRET_ACCESS_KEY` | Your AWS secret access key. Used in conjunction with `AWS_ACCESS_KEY_ID`. | | `AWS_SESSION_TOKEN` | (Optional) The session token for temporary AWS credentials. | | `AWS_PROFILE` | The name of the AWS profile to use from your AWS credentials file (`~/.aws/credentials`). | | `LOCALSTACK_AUTH_TOKEN` | Used for testing with LocalStack; typically not needed for standard deployments. | You can configure your AWS credentials using `aws configure` or `aws configure sso` via the AWS CLI. ### Configuration Files #### `pyproject.toml` (and project structure) Shuttle Cobra projects are standard Python projects, typically managed with `pyproject.toml`. Your application code, including `@shuttle_task.cron` decorated functions, resides within your project's Python source files (e.g., `main.py` or `src/my_project/task.py`). ```toml [project] name = "my-shuttle-project" version = "0.1.0" dependencies = [ "shuttle-cobra", # ... other dependencies ] ``` ### Common Workflows #### First Deployment ```bash uv venv source .venv/bin/activate uv add shuttle # Add your Shuttle Cobra code and dependencies (e.g., shuttle-aws, shuttle-db) uv run -m shuttle deploy # Deploy to AWS infrastructure managed by Shuttle # OR shuttle deploy uv run -m shuttle run # Test locally against provisioned infrastructure # OR shuttle run ``` #### Development Cycle ```bash uv run -m shuttle deploy # Deploy changes # OR shuttle deploy uv run -m shuttle run # Develop locally against provisioned infrastructure # OR shuttle run uv run -m shuttle logs # Check deployment logs # OR shuttle logs ``` #### Project Management ```bash # The Python CLI manages projects through their local paths. # To remove a project and its deployed resources: uv run -m shuttle destroy # OR shuttle destroy ``` #### Debugging ```bash uv run -m shuttle logs # Check recent logs # OR shuttle logs uv run -m shuttle deploy --debug # Verbose deployment (if --debug is implemented) # OR shuttle deploy --debug ``` ### Troubleshooting #### Common Issues **AWS Authentication issues:** * Ensure your AWS credentials are correctly configured via environment variables or `~/.aws/credentials`. * Use `aws configure` or `aws configure sso`. **Local development issues:** * Ensure you are in the correct virtual environment (`source .venv/bin/activate`). * Verify that your project path is correct (e.g., `.` for the current directory). * Check for `FileNotFoundError` if `main.py` or `__main__.py` is missing in your project root. **Deployment issues:** * Check `uv run -m shuttle logs` for build or deployment errors. * Ensure all Python dependencies are specified in `pyproject.toml` and installed (`uv add shuttle` or `uv sync` as appropriate). ### Getting Help ```bash uv run -m shuttle --help # General help # OR shuttle --help uv run -m shuttle --help # Command-specific help (if supported by click) # OR shuttle --help ``` For additional support: * [Discord Community](https://discord.gg/shuttle) * [GitHub Issues](https://github.com/shuttle-hq/shuttle/issues) * [Documentation](https://docs.shuttle.dev/) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://shuttle-1.gitbook.io/shuttle-cobra/reference/cli-reference.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.