# Bevy CLI MVP

A Bevy CLI is a [long-outstanding feature request](https://github.com/bevyengine/bevy/issues/436), with [even more](https://github.com/bevyengine/bevy/discussions/6026) discussion and analysis. Let's start building it!

Rather than being a single-purpose tool to accomplish a specific task, the vision is to create a single CLI entry point for tasks that best fit the CLI format.

Under the hood, the editor can then call the CLI for many of its tasks, avoiding duplication of effort and providing a mechanism for basic automation.

## So what might it do?

A number of ideas for functionality that would fit well in the Bevy CLI have been floated:

- project generation from a template
- creating final builds for specific platforms
- command-line driven asset preprocessing
- automated upgrades
- checks for known problems in environment configuration
- single method call CI checks
- runs Bevy-specific lints (see [the design document](/4ciCsSb7SxyqnteFzirEDA))

## How do we build it?

Requirements:

- not required to get started with Bevy: `cargo` alone should work fine to get to Hello World
- written in Rust

Hunches:

- built using the `clap` crate
- distributed using cargo as a [binary extension](https://doc.rust-lang.org/book/ch14-05-extending-cargo.html)
- leverage `cargo-generate` for templates

## Planning the work

Templates are the most important requirement here: useful for game jams, editor starter projects and tutorials. We should tackle this first, as it lays out a foundation while being relatively straightforward.

We should start this in the [`BevyFlock`](https://github.com/TheBevyFlock) community organization, and then transfer the repository to the [`bevyengine`](https://github.com/bevyengine) organization once the initial architecture has been blessed.

We should follow the same structural rules as the editor here:

- lives in a seperate repository under the Bevy org
- maintainers have merge rights
- depends on the latest Bevy release
- updated to the new Bevy release during the release candidate process
- can pull in 3rd party Bevy dependencies, but only cautiously and with consent from the crate authors

Once it's adopted, CLI-powered asset preprocesing is the next most important need: Bevy doesn't have any good alternative right now.

## Prior Art

- [cargo-bavy](https://github.com/TimJentzsch/cargo-bavy)
- [backpack](https://github.com/rusty-ferris-club/backpack)
- [bevyinit](https://github.com/nigrodev/bevyinit)

## About the prototype (release 0.1.0)

The prototype as of release `0.1.0` supports the following features:

- Bevy project generation from templates
- Out-of-the-box support for building and running Bevy apps in the browser
- [A Bevy-specific linter](https://github.com/TheBevyFlock/bevy_cli/blob/main/bevy_lint/README.md)

### Project scaffolding

The `bevy new` command lets you easily scaffold a new Bevy project using a custom template or a [minimal template provided by Bevy](https://github.com/TheBevyFlock/bevy_new_minimal).
Templates are just GitHub repositories and can be specified with the `-t` flag.

If the template is omitted, the [default minimal template](https://github.com/TheBevyFlock/bevy_new_minimal) will be chosen.

bevy new my-project

To use a specific template, provide the full GitHub URL

bevy new my-project -t https://github.com/TheBevyFlock/bevy_new_2d

Additionally, any repo prefixed with `bevy_new_` from the [TheBevyFlock](https://github.com/TheBevyFlock) will be usable via its shortcut form i.e. `-t 2d` will use the template [bevy_new_2d](https://github.com/TheBevyFlock/bevy_new_2d).

bevy new my-project -t 2d

### Bevy web apps

The CLI makes it easy to build and run web apps made with Bevy, using `bevy build web` and `bevy run web`. It takes care of compiling the app to Wasm, creating JavaScript bindings and serving it on a local web server to test it out. Necessary tools will also be installed automatically.
For more information see the Bevy Web Initiative [HackMD](https://hackmd.io/r15ulD6yR2G6kchYH0RQPw)

### Linter

The CLI has 1st-party support for `bevy_lint`. It must be installed first using the [installation guide](https://thebevyflock.github.io/bevy_cli/bevy_lint/index.html#installation), but then you can run the linter with the `lint` subcommand:

bevy lint

This command uses the same arguments as `cargo check`:

bevy lint --workspace --all-features

You can view a full list of supported options with:

bevy lint -- --help