|
| 1 | +# Bodo Usage |
| 2 | + |
| 3 | +This document describes the current features of Bodo and how to use them. |
| 4 | + |
| 5 | +## Installation & Setup |
| 6 | + |
| 7 | +You'll need [Rust](https://www.rust-lang.org/tools/install) installed. |
| 8 | + |
| 9 | +```bash |
| 10 | +git clone https://github.com/bodo-run/bodo |
| 11 | +cd bodo |
| 12 | +cargo install --path . --all-features |
| 13 | +``` |
| 14 | + |
| 15 | +## Command Overview |
| 16 | + |
| 17 | +### Basic Command Structure |
| 18 | + |
| 19 | +```bash |
| 20 | +bodo [OPTIONS] [TASK] [SUBTASK] [ARGS...] |
| 21 | +``` |
| 22 | + |
| 23 | +- **TASK**: The name of the task to run. If omitted, Bodo will attempt to run the default task (if available). |
| 24 | +- **SUBTASK**: An optional subtask name. |
| 25 | +- **ARGS...**: Additional arguments passed to the task's command. |
| 26 | + |
| 27 | +### Common Flags |
| 28 | + |
| 29 | +| Flag | Shorthand | Description | |
| 30 | +|------|-----------|-------------| |
| 31 | +| `--list` | `-l` | Lists all available tasks from all loaded scripts. | |
| 32 | +| `--watch` | `-w` | Runs the specified task and re-runs it whenever watched files change. | |
| 33 | +| `--auto-watch` | | Automatically enables watch mode if tasks define watch configurations. | |
| 34 | +| `--debug` | | Enables debug logging (sets `RUST_LOG=bodo=debug`). | |
| 35 | + |
| 36 | +### Examples |
| 37 | + |
| 38 | +- Run the default task: |
| 39 | + ```bash |
| 40 | + bodo |
| 41 | + ``` |
| 42 | + |
| 43 | +- Run a specific task: |
| 44 | + ```bash |
| 45 | + bodo test |
| 46 | + ``` |
| 47 | + |
| 48 | +- Run a subtask: |
| 49 | + ```bash |
| 50 | + bodo deploy prod |
| 51 | + ``` |
| 52 | + |
| 53 | +- Pass additional arguments: |
| 54 | + ```bash |
| 55 | + bodo test watch -- --nocapture --test-threads=1 |
| 56 | + ``` |
| 57 | + |
| 58 | +- Enable watch mode: |
| 59 | + ```bash |
| 60 | + bodo --watch test |
| 61 | + ``` |
| 62 | + |
| 63 | +- List tasks: |
| 64 | + ```bash |
| 65 | + bodo --list |
| 66 | + ``` |
| 67 | + |
| 68 | +## How Bodo Finds and Loads Tasks |
| 69 | + |
| 70 | +Bodo searches for task definitions in: |
| 71 | +- A root-level `script.yaml` (if provided). |
| 72 | +- Any YAML files in a `scripts/` directory (searched recursively). |
| 73 | +- Tasks defined in these files are parsed and stored in a dependency graph. |
| 74 | + |
| 75 | +### Key Points |
| 76 | +- The `default_task` in each script is executed if you invoke that script without specifying a task. |
| 77 | +- Tasks are defined under a `tasks:` section. |
| 78 | +- Cross-file task references (e.g., `"../other.yaml/some-task"`) are automatically resolved. |
| 79 | + |
| 80 | +## Defining Tasks |
| 81 | + |
| 82 | +Tasks are defined in YAML files. Here is an example of a task file: |
| 83 | + |
| 84 | +```yaml |
| 85 | +name: "exampleScript" |
| 86 | +description: "This is an example script." |
| 87 | + |
| 88 | +default_task: |
| 89 | + command: echo "Hello from default task!" |
| 90 | + description: "Runs by default if no task is specified." |
| 91 | + |
| 92 | +tasks: |
| 93 | + example: |
| 94 | + description: "An example task." |
| 95 | + command: echo "Running example task..." |
| 96 | + env: |
| 97 | + EXAMPLE_VAR: "123" |
| 98 | + watch: |
| 99 | + patterns: |
| 100 | + - "src/**/*.rs" |
| 101 | + debounce_ms: 1000 |
| 102 | +``` |
| 103 | +
|
| 104 | +### Available Task Fields |
| 105 | +- `description` (string): Brief help text. |
| 106 | +- `command` (string): Shell command to run (executed using `sh -c`). |
| 107 | +- `cwd` (string): Optional working directory. |
| 108 | +- `env` (map): Environment variables for the task. |
| 109 | +- `watch` (object): Configuration for file watching. |
| 110 | +- `timeout` (string): Timeout duration (e.g., "30s", "1m"); enforced by the TimeoutPlugin. |
| 111 | +- `pre_deps` and `post_deps` (arrays): Define tasks or commands to run before/after the task. |
| 112 | +- `concurrently` (array): Defines a group of tasks/commands to run in parallel (handled by the ConcurrentPlugin). |
| 113 | + |
| 114 | +## Listing Tasks |
| 115 | + |
| 116 | +Use the following command to list all tasks: |
| 117 | +```bash |
| 118 | +bodo --list |
| 119 | +``` |
| 120 | + |
| 121 | +This command triggers the PrintListPlugin, which displays a grouped list of tasks from all discovered YAML files. |
| 122 | + |
| 123 | +## Concurrency |
| 124 | + |
| 125 | +Tasks can run parts of their workflow concurrently. For example: |
| 126 | + |
| 127 | +```yaml |
| 128 | +default_task: |
| 129 | + description: "Run two commands in parallel." |
| 130 | + concurrently_options: |
| 131 | + fail_fast: true # Stop all tasks if one fails. |
| 132 | + max_concurrent_tasks: 2 |
| 133 | + concurrently: |
| 134 | + - task: test |
| 135 | + - command: "echo 'Hello Parallel World'" |
| 136 | +``` |
| 137 | + |
| 138 | +- `fail_fast`: If any concurrent task fails, remaining tasks are terminated. |
| 139 | +- `max_concurrent_tasks`: Limits the number of tasks that run at the same time. |
| 140 | + |
| 141 | +## Watch Mode |
| 142 | + |
| 143 | +Tasks can be configured to automatically re-run when specified files change. Example configuration: |
| 144 | + |
| 145 | +```yaml |
| 146 | +tasks: |
| 147 | + test: |
| 148 | + command: cargo test |
| 149 | + watch: |
| 150 | + patterns: |
| 151 | + - "src/**/*.rs" |
| 152 | + - "tests/**/*.rs" |
| 153 | + debounce_ms: 1000 |
| 154 | + ignore_patterns: |
| 155 | + - "target/**" |
| 156 | +``` |
| 157 | + |
| 158 | +Then run: |
| 159 | +```bash |
| 160 | +bodo --watch test |
| 161 | +``` |
| 162 | + |
| 163 | +Bodo will: |
| 164 | +1. Execute the test task. |
| 165 | +2. Monitor files matching the specified patterns. |
| 166 | +3. Re-run the task when changes are detected. |
| 167 | + |
| 168 | +## Debug Logging |
| 169 | + |
| 170 | +Enable debug logs by using the `--debug` flag or setting the environment variable: |
| 171 | + |
| 172 | +```bash |
| 173 | +bodo --debug test |
| 174 | +``` |
| 175 | + |
| 176 | +This will output additional information about plugin execution, dependency resolution, and process management. |
| 177 | + |
| 178 | +## Environment Variables |
| 179 | +- Global environment variables can be set for Bodo (e.g., `BODO_LOG_LEVEL`, `BODO_TASK_PATH`). |
| 180 | +- Tasks can define their own `env` map, which is merged with any global environment settings. |
| 181 | + |
| 182 | +Example: |
| 183 | +```bash |
| 184 | +export BODO_LOG_LEVEL=debug |
| 185 | +bodo test |
| 186 | +``` |
| 187 | + |
| 188 | +## Exit Codes |
| 189 | +- Bodo exits with a non-zero code if any task or command fails. |
| 190 | +- In concurrency mode with `fail_fast` enabled, if one task fails, Bodo attempts to terminate all other tasks and exits non-zero. |
| 191 | + |
| 192 | +## Future / Unimplemented Features |
| 193 | +- **Interactive TUI**: The `--interactive` mode for selecting tasks is not yet implemented. |
| 194 | +- **ASCII Graph Visualization**: Although referenced in the design documentation, a `--graph` flag is not available. |
| 195 | +- **Sandbox Mode**: No sandboxing features are currently implemented. |
| 196 | +- **Failing Plugin**: A stub exists but has no functionality. |
| 197 | + |
| 198 | +## Practical Examples |
| 199 | + |
| 200 | +1. Run the default task: |
| 201 | + ```bash |
| 202 | + bodo |
| 203 | + ``` |
| 204 | + |
| 205 | +2. List all tasks: |
| 206 | + ```bash |
| 207 | + bodo --list |
| 208 | + ``` |
| 209 | + |
| 210 | +3. Run a build task in watch mode: |
| 211 | + ```bash |
| 212 | + bodo --watch build |
| 213 | + ``` |
| 214 | + |
| 215 | +4. Deploy using a subtask: |
| 216 | + ```bash |
| 217 | + bodo deploy prod |
| 218 | + ``` |
| 219 | + |
| 220 | +5. Run tests with custom arguments: |
| 221 | + ```bash |
| 222 | + bodo test -- --test-threads=1 |
| 223 | + ``` |
| 224 | + |
| 225 | +6. Enable debug logging: |
| 226 | + ```bash |
| 227 | + bodo --debug test |
| 228 | + ``` |
| 229 | + |
| 230 | +This usage document covers the current capabilities of Bodo. For additional features or changes, refer to the design documentation and plugin interface for further customization. |
| 231 | + |
0 commit comments