{"id":34126421,"url":"https://github.com/8bitalex/raid","last_synced_at":"2026-04-29T02:15:00.872Z","repository":{"id":311206703,"uuid":"966580385","full_name":"8bitAlex/raid","owner":"8bitAlex","description":"Declarative development workflow orchestrator — a cross-platform Go CLI that runs team commands, environments, and workflows from version-controlled YAML. Works on macOS, Linux, and Windows.","archived":false,"fork":false,"pushed_at":"2026-04-29T00:27:01.000Z","size":9643,"stargazers_count":5,"open_issues_count":18,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-29T00:27:18.125Z","etag":null,"topics":["cli","command-line-tool","developer-experience","developer-tools","devops","devops-tools","distributed-systems","dx","go","golang","multi-repo","task-runner","yaml"],"latest_commit_sha":null,"homepage":"http://raidcli.dev/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/8bitAlex.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"8bitalex","buy_me_a_coffee":"8bitalex"}},"created_at":"2025-04-15T06:25:36.000Z","updated_at":"2026-04-29T00:14:43.000Z","dependencies_parsed_at":"2025-09-28T07:15:31.107Z","dependency_job_id":"59ef6934-c963-4835-adae-8c1d48643274","html_url":"https://github.com/8bitAlex/raid","commit_stats":null,"previous_names":["8bitalex/raid"],"tags_count":18,"template":false,"template_full_name":null,"purl":"pkg:github/8bitAlex/raid","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/8bitAlex%2Fraid","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/8bitAlex%2Fraid/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/8bitAlex%2Fraid/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/8bitAlex%2Fraid/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/8bitAlex","download_url":"https://codeload.github.com/8bitAlex/raid/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/8bitAlex%2Fraid/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32407277,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-28T19:38:08.556Z","status":"online","status_checked_at":"2026-04-29T02:00:06.602Z","response_time":110,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","command-line-tool","developer-experience","developer-tools","devops","devops-tools","distributed-systems","dx","go","golang","multi-repo","task-runner","yaml"],"created_at":"2025-12-14T23:41:39.675Z","updated_at":"2026-04-29T02:15:00.862Z","avatar_url":"https://github.com/8bitAlex.png","language":"Go","funding_links":["https://github.com/sponsors/8bitalex","https://buymeacoffee.com/8bitalex"],"categories":[],"sub_categories":[],"readme":"# Raid - Declarative development environment orchestrator\n\n\u003cp align=\"center\"\u003e\n\u003ca href=\"https://github.com/8bitAlex/raid/actions/workflows/build.yml\"\u003e\u003cimg src=\"https://github.com/8bitAlex/raid/actions/workflows/build.yml/badge.svg\" alt=\"Build and Test\"\u003e\u003c/a\u003e\n\u003ca href=\"https://codecov.io/github/8bitAlex/raid\"\u003e\u003cimg src=\"https://codecov.io/github/8bitAlex/raid/graph/badge.svg?token=Z75V7I2TLW\" alt=\"codecov\"\u003e\u003c/a\u003e\n\u003ca href=\"https://goreportcard.com/report/github.com/8bitAlex/raid\"\u003e\u003cimg src=\"https://goreportcard.com/badge/github.com/8bitAlex/raid\" alt=\"Go Report Card\"\u003e\u003c/a\u003e\n\u003cbr\u003e\n\u003cimg src=\"https://img.shields.io/github/v/release/8bitAlex/raid?label=Stable\u0026color=green\" alt=\"Stable\"\u003e\n\u003cimg src=\"https://img.shields.io/badge/dynamic/regex?url=https%3A%2F%2Fraw.githubusercontent.com%2F8bitAlex%2Fraid%2Fmain%2Fsrc%2Fresources%2Fapp.properties\u0026search=version%3D(.%2B)\u0026replace=%241\u0026label=Latest\u0026color=blue\" alt=\"Latest\"\u003e\n\u003cimg src=\"https://img.shields.io/github/last-commit/8bitAlex/raid?label=Last%20Updated\" alt=\"Last Updated\"\u003e\n\u003cbr\u003e\n\u003cimg src=\"https://img.shields.io/badge/platforms-Windows%20%7C%20macOS%20%7C%20Linux-blue\" alt=\"Platforms\"\u003e\n\u003c/p\u003e\n\n\u003cbr/\u003e\n\n**Raid is a cross-platform, open-source CLI that turns your team's multi-repo development environment into version-controlled YAML.** Stop losing hours to wiki archaeology, stale setup scripts, and \"what's the command for that again?\" Slack threads — define commands, environments, and workflows once and let every developer run them the same way on macOS, Linux, and Windows.\n\nIt's more than *just* a command runner.\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"docs/assets/raid-comparison.gif\" alt=\"Raid vs. manual setup — side-by-side comparison of a multi-repo developer environment orchestrated with the raid CLI\"\u003e\n\u003c/p\u003e\n\n---\n\nEvery complex system has the same problem. There's a Confluence page from two years ago, a Slack thread with the \"actual\" way to start the proxy, a bash script that lives on one person's machine, and a handful of developers who've memorized what everyone else has to ask about. Running the test suite, patching a dependency, switching to staging, deploying a service — each one is a small excavation through wikis, READMEs, and tribal knowledge. It works until someone leaves, or until the script quietly breaks.\n\n**Raid replaces all of it.** Define your team's commands, environments, and workflows as YAML that lives in the repository — versioned, shared, and executable. Anyone can run `raid test`, `raid patch`, or `raid deploy` correctly, consistently, without reading docs or asking another dev.\n\n```bash\nraid install    # clone all repos and set up the full environment\nraid env local  # switch everything to local — all repos, all at once\nraid test       # run the test suite — however this repo defines that\nraid patch      # apply a patch — whatever that means for this service\n```\n\nThe config commits with the code. When the process changes, the command changes with it — one place, not scattered across wikis, scripts, and memory.\n\n📖 For the full design rationale, see the [design proposal](https://alexsalerno.dev/blog/raid-design-proposal).\n\n---\n\n## How Raid works\n\nA **profile** (`*.raid.yaml`) describes your full system: which repos to clone, what environments exist, and what commands the team uses. It lives in a YAML file you register with raid once.\n\nEach **repository** can commit its own `raid.yaml` at its root, defining the commands and environment config specific to that service. Raid merges these automatically when the profile loads.\n\nWhen a developer runs any raid command, it executes against the right repo, in the right environment, with the right variables — no manual steps, no guessing.\n\n---\n\n## Key Features\n\n- **Commands that live with the code** — `raid test`, `raid patch`, `raid proxy` — define once in YAML, run anywhere. No more tracking down scripts or asking how something works.\n- **Consistent environments** — define local, staging, and production environments once. `raid env staging` applies the right variables and tasks across every repo in a single command.\n- **Full system orchestration** — manage any number of repos as a single unit. Clone, configure, and run them together or individually.\n- **Rich task runner** — 11 built-in task types: shell commands, scripts, HTTP downloads, git operations, health checks, template rendering, prompts, confirmations, and more.\n- **AI-ready context** — `raid context` emits an MCP-shaped snapshot of the workspace, and `raid context serve` runs raid as an MCP server so AI agents can read repo state and invoke commands directly.\n- **Portable** — config is just YAML in the repo. Works on macOS, Linux, and Windows.\n\n---\n\n## Why Raid? (vs. Make, Taskfile, Just, and docker-compose)\n\nMost task runners are built to orchestrate a *single project*. Raid is built for the problem one layer up: **operating a multi-repo development environment** as a team. Here's how it compares to tools you might already use:\n\n| Capability                                    | Raid | Make | Taskfile | Just | docker-compose |\n|------------------------------------------------|:----:|:----:|:--------:|:----:|:--------------:|\n| Declarative YAML config                        |  ✅  |  ❌  |    ✅    |  ❌  |       ✅       |\n| Multi-repo orchestration                       |  ✅  |  ❌  |    ❌    |  ❌  |       ❌       |\n| Merges top-level profile + per-repo config     |  ✅  |  ❌  |    ❌    |  ❌  |       ❌       |\n| Named environments (local / staging / prod)    |  ✅  |  ❌  |    ❌    |  ❌  |      ⚠️       |\n| Built-in `Git`, `HTTP`, `Wait`, `Prompt` tasks |  ✅  |  ❌  |    ❌    |  ❌  |       ❌       |\n| Cross-platform (macOS / Linux / Windows)       |  ✅  |  ⚠️  |    ✅    |  ✅  |       ✅       |\n| JSON Schema autocomplete via SchemaStore       |  ✅  |  ❌  |    ❌    |  ❌  |      ⚠️       |\n| Custom `raid \u003ccmd\u003e` subcommands in `--help`    |  ✅  |  ❌  |    ✅    |  ✅  |       ❌       |\n\n**Use Raid when** your team works across more than one repository and needs a single, consistent way to clone repos, switch environments, and run day-to-day commands.\n\n**Skip Raid when** you're building a single-language project in isolation — a standard build tool (Make, Taskfile, npm scripts, cargo) is probably all you need.\n\n---\n\n## Development Status\n\nRaid is currently in the **prototype stage**. Core functionality is still being explored and iterated on — expect frequent changes and incomplete features.\n\nFeedback, issues, and contributions are welcome as the project takes shape.\n\n---\n\n## Getting Started\n\n### Installation\n\n**macOS**\n```bash\nbrew install 8bitalex/tap/raid\n```\n\n**Linux**\n```bash\ncurl -fsSL https://raw.githubusercontent.com/8bitalex/raid/main/install.sh | bash\n```\n\n**Windows**\n\n1. Go to the [latest release](https://github.com/8bitalex/raid/releases/latest) and download `raid_\u003cversion\u003e_windows_amd64.zip`\n2. Extract the zip — you'll find `raid.exe` inside\n3. Move `raid.exe` to a folder that's on your `PATH` (e.g. `C:\\Program Files\\raid\\`)\n4. If you moved it to a new folder, add that folder to your `PATH`:\n   - Open **Settings** → **System** → **About** → **Advanced system settings**\n   - Click **Environment Variables** → select **Path** under System variables → **Edit** → **New**\n   - Paste the folder path and click OK\n5. Open a new terminal and verify: `raid --version`\n\n**Preview builds**\n\nWant to try the latest features before they ship? Install the preview channel — it receives updates ahead of stable and may include experimental functionality.\n\n```bash\n# macOS / Linux (Homebrew)\nbrew install 8bitalex/tap/raid-preview\n```\n\nYou can also download preview binaries directly from the [GitHub releases page](https://github.com/8bitalex/raid/releases). Preview builds are tagged with a `-preview` suffix (e.g. `0.6.0-preview`) and update independently from stable. You can have both installed side-by-side.\n\n### Quickstart\n\n```bash\nraid profile create   # interactive wizard: name your profile and add repositories\nraid install          # clone repos and run install tasks\n```\n\nYou can also write a profile file manually (see [Configuration](#configuration)) and register it with `raid profile add \u003cfile\u003e`.\n\n---\n\n## Commands\n\n### `raid profile`\n\nManage profiles. A profile is a named collection of repositories and environments.\n\n- `raid profile create` — interactive wizard to create and register a new profile\n- `raid profile add \u003cfile\u003e` — register profiles from a YAML or JSON file\n- `raid profile list` — list all registered profiles\n- `raid profile \u003cname\u003e` — switch the active profile\n- `raid profile remove \u003cname\u003e` — remove a profile\n\n### `raid install`\n\nClone all repositories in the active profile and run any configured install tasks. Already-cloned repos are skipped.\n\n- `raid install` — clone all repos and run install tasks\n- `raid install \u003crepo\u003e` — clone and install a single named repository only (profile-level install tasks are not run)\n\nClones run concurrently. Use `-t` to cap the number of concurrent clone threads.\n\n### `raid env`\n\n- `raid env \u003cname\u003e` — apply a named environment: writes `.env` files into each repo and runs environment tasks\n- `raid env` — show the currently active environment\n- `raid env list` — list available environments\n\n### `raid context`\n\nPrint a condensed snapshot of the active workspace — profile, environment, repos with live git state, custom commands, and recent command-run history.\n\n- `raid context` — human-readable summary\n- `raid context --json` — MCP-shaped JSON for AI agents\n- `raid context serve` — run raid as a [Model Context Protocol](https://modelcontextprotocol.io) server over stdio, exposing workspace state as resources and raid actions (`raid_install`, `raid_env_switch`, `raid_run_task`, …) as tools\n\n### `raid doctor`\n\nCheck the current configuration for issues and get suggestions for fixing them. Useful after initial setup or when something isn't working as expected.\n\n### `raid \u003ccommand\u003e`\n\nRun a custom command defined in the active profile or any of its repositories.\n\n```bash\nraid test         # run the \"test\" command\nraid patch        # run the \"patch\" command\nraid deploy       # run the \"deploy\" command\n```\n\nArguments passed after the command name are available inside tasks as `$RAID_ARG_1`, `$RAID_ARG_2`, etc.\n\n```bash\nraid deploy staging v1.2.3   # $RAID_ARG_1=staging, $RAID_ARG_2=v1.2.3\n```\n\nCustom commands appear alongside built-in commands in `raid --help`. Commands defined in a profile take priority over same-named commands from repositories.\n\n---\n\n## Configuration\n\n### Profile (`*.raid.yaml`)\n\nA profile defines the repositories, environments, and tasks for a project. The `$schema` annotation enables autocomplete and validation in editors like VS Code. See [Tasks](#tasks) for available task types.\n\nSupported formats: `.yaml`, `.yml`, `.json`\n\nExample `my-project.raid.yaml`:\n```yaml\n# yaml-language-server: $schema=https://raw.githubusercontent.com/8bitalex/raid/main/schemas/raid-profile.schema.json\n\nname: my-project\n\nrepositories:\n  - name: frontend\n    path: ~/Developer/frontend\n    url: https://github.com/myorg/frontend\n  - name: backend\n    path: ~/Developer/backend\n    url: https://github.com/myorg/backend\n\nenvironments:\n  - name: dev\n    variables:\n      - name: NODE_ENV\n        value: development\n      - name: DATABASE_URL\n        value: postgresql://localhost:5432/myproject\n    tasks:\n      - type: Print\n        message: \"Applying dev environment...\"\n        color: green\n      - type: Shell\n        cmd: docker compose up -d\n      - type: Wait\n        url: localhost:5432\n        timeout: 30s\n\ninstall:\n  tasks:\n    - type: Shell\n      cmd: brew install node\n\ntask_groups:\n  verify-services:\n    - type: Wait\n      url: http://localhost:3000\n      timeout: 10s\n    - type: Wait\n      url: localhost:5432\n      timeout: 10s\n\ncommands:\n  - name: sync\n    usage: \"Pull latest on all repos and restart services\"\n    tasks:\n      - type: Git\n        op: pull\n        path: ~/Developer/frontend\n      - type: Git\n        op: pull\n        path: ~/Developer/backend\n      - type: Shell\n        cmd: docker compose restart\n      - type: Group\n        ref: verify-services\n```\n\nMultiple profiles can be defined in a single file using YAML document separators (`---`) or a JSON array.\n\n### Repository (`raid.yaml`)\n\nIndividual repositories can carry their own `raid.yaml` at their root to define repo-specific environments and commands. These are merged with the profile configuration at load time. Committing this file to each repo is the primary way knowledge is shared — the command for running tests, applying patches, or starting a proxy lives here instead of in a wiki.\n\n```yaml\n# yaml-language-server: $schema=https://raw.githubusercontent.com/8bitalex/raid/main/schemas/raid-repo.schema.json\n\nname: my-service\nbranch: main\n\nenvironments:\n  - name: dev\n    tasks:\n      - type: Shell\n        cmd: npm install\n      - type: Shell\n        cmd: npm run build\n\ncommands:\n  - name: test\n    usage: \"Run the test suite\"\n    tasks:\n      - type: Shell\n        cmd: npm test\n```\n\n---\n\n## Tasks\n\nTasks are the unit of work in raid. They appear in environments, install steps, commands, and task groups. Each task has a `type` and type-specific fields.\n\nTasks fall into two categories:\n\n- **Primitive tasks** are the general-purpose building blocks. They can express virtually any operation and are the foundation everything else is built on.\n- **Convenience tasks** are higher-level wrappers around common operations. Anything they do could technically be written with a primitive task, but using a purpose-built type is clearer, safer, and cross-platform.\n\n**Primitive tasks**\n\n| Type | Description |\n|------|-------------|\n| `Script` | Execute a script file |\n| `Set` | Set a variable to a static or derived value |\n| `Shell` | Run a shell command |\n\n**Convenience tasks**\n\n| Type | Description |\n|------|-------------|\n| `Confirm` | Prompt the user for a yes/no confirmation |\n| `Git` | Run a git operation (`pull`, `checkout`, `fetch`, `reset`) |\n| `Group` | Execute a named task group by `ref` |\n| `HTTP` | Download a file from a URL |\n| `Print` | Print a message to the console |\n| `Prompt` | Prompt the user for input and store it in a variable |\n| `Template` | Render a template file |\n| `Wait` | Poll a URL or address until it responds |\n\nAll task types support two optional modifiers:\n\n```yaml\nconcurrent: true   # run in parallel with other concurrent tasks\ncondition:         # skip this task unless all conditions are met\n  platform: darwin # only on this OS (darwin, linux, windows)\n  exists: ~/.config/myapp  # only if this path exists\n  cmd: which docker        # only if this command exits 0\n```\n\n### Confirm\n\nPause and require explicit confirmation (`y` or `yes`) before continuing. Useful before destructive operations.\n\n```yaml\n- type: Confirm\n  message: \"This will reset the production database. Continue?\"\n```\n\n### Git\n\nPerform a git operation in a repository directory.\n\n```yaml\n- type: Git\n  op: pull          # pull, checkout, fetch, reset\n  branch: main      # required for checkout; optional for pull, fetch, reset\n  path: ~/Developer/myrepo  # optional, defaults to current directory\n```\n\n### Group\n\nExecute a named task group defined in the profile's `task_groups`. Supports optional parallel and retry modifiers.\n\n```yaml\n- type: Group\n  ref: verify-services\n  parallel: true   # optional: run all tasks in the group concurrently\n  attempts: 3      # optional: retry the group on failure\n  delay: 5s        # optional: delay between retries (default: 1s)\n```\n\n### HTTP\n\nDownload a file from a URL.\n\n```yaml\n- type: HTTP\n  url: https://example.com/config.json\n  dest: ~/.config/myapp/config.json\n```\n\n### Print\n\nPrint a formatted message to stdout. Useful for labelling steps in long task sequences.\n\n```yaml\n- type: Print\n  message: \"Deploying $APP_VERSION to production...\"\n  color: yellow    # optional: red, green, yellow, blue, cyan, white\n  literal: false   # optional: skip env var expansion\n```\n\n### Prompt\n\nAsk the user for input and store the result in an environment variable for use by downstream tasks.\n\n```yaml\n- type: Prompt\n  var: TARGET_ENV\n  message: \"Which environment? (dev/staging/prod)\"\n  default: dev     # optional: used when user presses enter with no input\n```\n\n### Script\n\nExecute a script file directly.\n\n```yaml\n- type: Script\n  path: ./scripts/setup.sh\n  runner: bash     # optional: bash, sh, zsh, python, python2, python3, node, powershell\n```\n\n### Set\n\nSet a variable to a static or derived value, making it available to all subsequent tasks. Values persist across runs in `~/.raid/vars`.\n\n```yaml\n- type: Set\n  var: DEPLOY_TARGET\n  value: production         # supports $VAR and ${VAR} expansion\n```\n\n```yaml\n# Build a derived value from earlier Prompt input\n- type: Prompt\n  var: VERSION\n  message: \"Version to deploy:\"\n- type: Set\n  var: IMAGE_TAG\n  value: \"myapp:$VERSION\"\n- type: Shell\n  cmd: docker push $IMAGE_TAG\n```\n\n**Variable precedence** (highest to lowest):\n1. `Set` task values\n2. Variables exported by Shell tasks in the current command run\n3. OS environment variables\n\n### Shell\n\nRun a command string in a configurable shell.\n\n```yaml\n- type: Shell\n  cmd: echo \"hello $USER\"\n  shell: bash      # optional: bash (default), sh, zsh, powershell, pwsh, ps, cmd\n  literal: false   # optional: skip env var expansion before passing to shell\n  path: ~/project  # optional: working directory. Defaults to ~ for profile tasks, repo dir for repo tasks\n```\n\n**Shell variable propagation** — variables exported inside a Shell task are automatically captured and made available to subsequent tasks in the same command run. This means you can compute a value in one Shell task and reference it in a later `Set` task or another Shell task:\n\n```yaml\ncommands:\n  - name: release\n    tasks:\n      - type: Shell\n        cmd: |\n          VERSION=$(git describe --tags --abbrev=0)\n          export VERSION\n      - type: Set\n        var: RELEASE_TAG\n        value: myapp:$VERSION   # $VERSION was exported above\n      - type: Shell\n        cmd: docker push $RELEASE_TAG\n```\n\nShell-local variables used within the same task (never exported) are resolved by the shell itself and are not visible to later tasks.\n\nExported variables live only for the duration of the current command run. They are available to every task that follows within the same invocation, but are **not persisted** between runs — the next time the command is invoked, the value is gone. Use a `Set` task if you need a value to persist across runs (values set that way are stored in `~/.raid/vars`).\n\n**Exit code propagation** — when a Shell task exits with a non-zero status, raid stops executing the current command and exits with the same exit code. No additional noise is printed beyond what the shell command itself wrote to stderr.\n\n### Template\n\nRender a file by substituting `$VAR` and `${VAR}` references with environment variable values.\n\n```yaml\n- type: Template\n  src: ./config/app.env.template\n  dest: ~/.config/myapp/app.env\n```\n\n### Wait\n\nPoll an HTTP(S) URL or TCP address until it responds, then continue.\n\n```yaml\n- type: Wait\n  url: http://localhost:8080/health  # or TCP: localhost:5432\n  timeout: 60s                       # optional, default: 30s\n```\n\n---\n\n## Commands Configuration\n\nCustom commands are defined in the `commands` array of a profile or repository `raid.yaml`. They become first-class `raid \u003cname\u003e` subcommands at runtime.\n\n```yaml\ncommands:\n  - name: deploy\n    usage: \"Build and deploy all services\"   # shown in raid --help\n    tasks:\n      - type: Confirm\n        message: \"Deploy to production?\"\n      - type: Shell\n        cmd: make deploy\n    out:                   # optional — defaults to full stdout+stderr when omitted\n      stdout: true\n      stderr: false\n      file: $DEPLOY_LOG    # also write all output here; supports $VAR expansion\n```\n\n**`name`** (required) — the subcommand name; e.g. `name: deploy` is invoked as `raid deploy`. Cannot shadow built-in names (`profile`, `install`, `env`, `doctor`, `help`, `version`, `completion`).\n\n**`usage`** (optional) — short description shown next to the command in `raid --help`.\n\n**`tasks`** (required) — the task sequence to run. All standard task types are supported.\n\n**`out`** (optional) — controls output handling. When omitted, stdout and stderr behave normally. When present:\n- `stdout` — show task stdout (default: `true` when `out` is omitted; set explicitly when using `out`)\n- `stderr` — show task stderr (default: `true` when `out` is omitted; set explicitly when using `out`)\n- `file` — additionally write all output to this path; supports `$VAR` expansion\n\n**Priority** — when a profile and one of its repositories define a command with the same name, the profile's definition wins.\n\n**Arguments** — any arguments passed after the command name are exposed as environment variables `RAID_ARG_1`, `RAID_ARG_2`, etc. and are available to all tasks in the command.\n\n```yaml\ncommands:\n  - name: deploy\n    usage: \"Deploy a service to an environment\"\n    tasks:\n      - type: Shell\n        cmd: ./deploy.sh $RAID_ARG_1 $RAID_ARG_2\n```\n```bash\nraid deploy staging v1.2.3   # $RAID_ARG_1=staging, $RAID_ARG_2=v1.2.3\n```\n\n**Repo metadata** — every repository in the active profile is auto-exposed as `RAID_REPO_\u003cNAME\u003e_URL`, `RAID_REPO_\u003cNAME\u003e_PATH`, and `RAID_REPO_\u003cNAME\u003e_BRANCH`. The name is uppercased with non-alphanumerics replaced by `_` (so `my-api` becomes `RAID_REPO_MY_API_URL`).\n\n```yaml\n- type: Shell\n  cmd: gh pr create --repo $RAID_REPO_MY_API_URL --base $RAID_REPO_MY_API_BRANCH\n  path: $RAID_REPO_MY_API_PATH\n```\n\n---\n\n## Best Practices\n\n**Commit `raid.yaml` to each repo.** The command for running tests, applying a patch, or starting the proxy belongs in the repo — not in a wiki, a Slack thread, or someone's memory. Anyone with raid picks it up automatically.\n\n**Use `commands` to codify team workflows.** Repeated operational tasks — patching, proxying, deploying, verifying — belong in `commands`. Anyone on the team can run `raid deploy` without knowing the steps. Use `task_groups` for reusable internal sequences that commands compose from.\n\n**Gate destructive steps with `Confirm`.** Any task sequence that resets data, force-pushes, or modifies production should begin with a `Confirm` task to prevent accidental runs.\n\n**Use `Print` to structure long sequences.** Clear section headers make install and deploy output readable at a glance.\n\n**Keep profiles in a dotfiles repo.** Profile files reference your repos and environments. Storing them in a private dotfiles repo keeps them version-controlled and accessible across machines.\n\n**Never commit secrets.** Use environment variable references or keep sensitive values in private profiles — never hardcode credentials in a committed raid file.\n\n---\n\n## FAQ\n\n### What is Raid?\n\nRaid is an open-source, cross-platform CLI tool that orchestrates development tasks, environments, and workflows across multiple Git repositories. Configuration lives in YAML files committed alongside the code, so every developer on the team runs the same commands the same way — no wiki archaeology, no setup scripts living on one person's laptop.\n\n### How is Raid different from Make, Taskfile, or Just?\n\nMake, Taskfile, and Just run tasks inside a single project. Raid is designed for **multi-repo** development environments: it clones repositories, merges a top-level profile with per-repo `raid.yaml` files, switches environment variables across every repo at once, and exposes custom `raid \u003ccmd\u003e` subcommands that anyone on the team can run. See [Why Raid?](#why-raid-vs-make-taskfile-just-and-docker-compose) above for a side-by-side comparison.\n\n### Does Raid work on Windows?\n\nYes. Raid builds for macOS, Linux, and Windows (amd64 and arm64 where applicable). See [Installation](#installation) for platform-specific instructions.\n\n### Where does Raid store its configuration?\n\nProfiles are registered in a [Viper](https://github.com/spf13/viper)-managed config file. Persisted variables from the `Set` task live in `~/.raid/vars`. Per-repo `raid.yaml` files live at the root of each repository and are committed to version control alongside the code they describe.\n\n### Can I use Raid with a monorepo?\n\nRaid is optimized for multi-repo setups, but it works for a single repo too — you can skip the top-level profile and commit a `raid.yaml` at the repo root to define commands, environments, and tasks for that project.\n\n### How do I share profiles across my team?\n\nCommit a `raid.yaml` in each service repository to share per-repo workflows — that's the primary mechanism. For team-wide profiles that span multiple repos, store them in a dotfiles repo or an internal shared repo and register them with `raid profile add \u003cfile\u003e`.\n\n### Does Raid support JSON Schema autocomplete in VS Code?\n\nYes. Raid's profile and repo schemas are published to [SchemaStore](https://www.schemastore.org/), so any editor that uses the schemastore catalog — VS Code with the [Red Hat YAML extension](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml), JetBrains IDEs, Neovim with `yaml-language-server`, Helix, and others — automatically associates `*.raid.yaml` and `raid.yaml` files with the correct schema. No manual `$schema` comment required.\n\n### Is Raid production-ready?\n\nRaid is currently in the **prototype stage**. Core functionality works and is usable today, but APIs and configuration may change as the project evolves. See [Development Status](#development-status).\n\n### How is \"Raid\" pronounced, and where does the name come from?\n\nIt's pronounced like the English word *raid* — as in a coordinated, objective-driven operation. The name reflects the tool's purpose: coordinating a group of repos to accomplish a single goal.\n\n---\n\n## Contributing\n\nContributions are welcome. See [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md) for details.\n\n## License\n\nLicensed under the **GNU General Public License v3.0**. See [LICENSE](LICENSE) for the full text.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F8bitalex%2Fraid","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F8bitalex%2Fraid","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F8bitalex%2Fraid/lists"}