{"id":46893676,"url":"https://github.com/opmr0/xeq","last_synced_at":"2026-04-02T15:45:20.925Z","repository":{"id":343209255,"uuid":"1176821790","full_name":"opmr0/xeq","owner":"opmr0","description":"xeq is a cross-platform CLI tool that runs sequences of commands from a single TOML file, making repetitive tasks fast and consistent","archived":false,"fork":false,"pushed_at":"2026-03-28T16:45:42.000Z","size":46594,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-28T18:27:09.725Z","etag":null,"topics":["automation","cli","command","command-line-tool","command-runner","toml"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/opmr0.png","metadata":{"files":{"readme":"readme.md","changelog":"changelog.md","contributing":"CONTRIBUTING.md","funding":null,"license":null,"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}},"created_at":"2026-03-09T12:14:03.000Z","updated_at":"2026-03-28T16:45:45.000Z","dependencies_parsed_at":"2026-03-12T00:01:16.102Z","dependency_job_id":null,"html_url":"https://github.com/opmr0/xeq","commit_stats":null,"previous_names":["opmr0/xeq"],"tags_count":19,"template":false,"template_full_name":null,"purl":"pkg:github/opmr0/xeq","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opmr0%2Fxeq","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opmr0%2Fxeq/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opmr0%2Fxeq/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opmr0%2Fxeq/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/opmr0","download_url":"https://codeload.github.com/opmr0/xeq/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opmr0%2Fxeq/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31309275,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T12:59:32.332Z","status":"ssl_error","status_checked_at":"2026-04-02T12:54:48.875Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["automation","cli","command","command-line-tool","command-runner","toml"],"created_at":"2026-03-10T23:22:11.850Z","updated_at":"2026-04-02T15:45:20.916Z","avatar_url":"https://github.com/opmr0.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\u003cimg src=\"./assets/logo_rounded.png\" alt=\"logo\" width=\"150\"/\u003e\n\n# xeq\n\n[![Crates.io](https://img.shields.io/crates/v/xeq)](https://crates.io/crates/xeq)\n[![Downloads](https://img.shields.io/crates/d/xeq)](https://crates.io/crates/xeq)\n[![License](https://img.shields.io/crates/l/xeq)](LICENSE)\n[![Build](https://github.com/opmr0/xeq/actions/workflows/release.yml/badge.svg)](https://github.com/opmr0/xeq/actions)\n[![Rust](https://img.shields.io/badge/rust-stable-orange)](https://www.rust-lang.org)\n\n**xeq runs sequences of commands from a single TOML file, making repetitive tasks fast and consistent.**\n\nEvery project has a setup ritual. Ten commands, always in the same order, every time. Write them once in a `xeq.toml`, commit it, and anyone on any OS runs the exact same steps with one command.\n\n\u003c/div\u003e\n\n---\n\n## Table of Contents\n\n- [Demo](#demo)\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n- [Comparison](#comparison)\n- [Commands](#commands)\n- [TOML Format](#toml-format)\n- [Features](#features)\n  - [1. Script Options](#1-script-options)\n  - [2. Variables](#2-variables)\n  - [3. Arguments](#3-arguments)\n  - [4. Environment Variables](#4-environment-variables)\n  - [5. Nested Scripts](#5-nested-scripts)\n  - [6. Parallel Execution](#6-parallel-execution)\n  - [7. Global Configuration](#7-global-configuration)\n  - [8. Run Summary](#8-run-summary)\n  - [9. Events](#9-events)\n  - [10. Custom Shells](#10-custom-shells)\n- [Examples](#examples)\n- [How It Works](#how-it-works)\n- [License](#license)\n\n---\n\n## Demo\n\n![demo](assets/demo.gif)\n\n## Installation\n\n**macOS / Linux**\n\n```bash\ncurl -sSf https://raw.githubusercontent.com/opmr0/xeq/main/install.sh | sh\n```\n\n**Windows (Powershell)**\n\n```powershell\niwr https://raw.githubusercontent.com/opmr0/xeq/main/install.ps1 -UseBasicParsing | iex\n```\n\n**Via cargo (Rust package manager)**\n\n```bash\ncargo install xeq\n```\n\n---\n\n## Quick Start\n\n**1. Create a `xeq.toml` in your project root:**\n\n```toml\n[setup]\nrun = [\n    \"npm install\",\n    \"npm run build\"\n]\n\n[dev]\nrun = [\"npm run dev\"]\n```\n\n**2. Run any script by name:**\n\n```bash\nxeq run setup\nxeq run dev\n```\n\nxeq finds `xeq.toml` in the current directory automatically. Use `xeq init` to generate a starter file.\n\n---\n\n## Comparison\n\n| Feature            | **xeq**              | **Makefile**       | **npm scripts** | **just**     |\n| ------------------ | -------------------- | ------------------ | --------------- | ------------ |\n| File type          | TOML                 | Makefile           | package.json    | Justfile     |\n| Cross-platform     | Yes                  | Mostly Linux/macOS | Yes             | Yes          |\n| Validation command | Yes (`xeq validate`) | No                 | No              | No           |\n| Variables          | Yes                  | Yes                | Limited         | Yes          |\n| Args support       | Yes                  | Limited            | Limited         | Yes          |\n| Nested scripts     | Yes (`xeq:`)         | Yes                | No              | Yes          |\n| Parallel execution | Yes                  | Yes (`-j`)         | No              | No           |\n| .env support       | Yes (auto)           | No                 | No              | Yes (opt-in) |\n| Init templates     | Yes (30+)            | No                 | No              | No           |\n\n---\n\n## Commands\n\n### `xeq run \u003cscript\u003e [flags]`\n\nRuns a script by name. Commands execute in order. If any command fails, xeq stops unless you pass `--continue-on-err`.\n\n```bash\nxeq run setup\nxeq run build --continue-on-err\nxeq run dev --quiet\nxeq run test --parallel\nxeq run create --args my-app\nxeq run deploy --args env=prod\n```\n\n| Flag                       | Short | Description                                                       |\n| -------------------------- | ----- | ----------------------------------------------------------------- |\n| `--continue-on-err`        | `-C`  | Keep going even if a command fails                                |\n| `--quiet`                  | `-q`  | Hide xeq's own log messages                                       |\n| `--clear`                  | `-c`  | Clear the terminal before each command                            |\n| `--parallel [threads]`     | `-p`  | Run all commands in parallel (default: logical CPU count)         |\n| `--args \u003cvalues...\u003e`       | `-a`  | Pass arguments into the script, positional or `key=value`         |\n| `--global`                 | `-g`  | Use the globally saved `xeq.toml` instead of the local one       |\n| `--summary`                | `-s`  | Print a timing summary after the script finishes                  |\n| `--dry-run`                | `-d`  | Preview commands without executing them                           |\n| `--no-events`              | `-e`  | Disable events for this run                                       |\n| `--allow-empty-args`       | `-A`  | Skip errors for missing variables or arguments                    |\n| `--no-env`                 |       | Skip loading the `.env` file                                      |\n| `--allow-recursion`        |       | Let a script call itself                                          |\n\n---\n\n### `xeq init [template]`\n\nCreates a starter `xeq.toml` in the current directory. Will not overwrite an existing file.\n\n```bash\nxeq init\nxeq init rust\nxeq init docker\n```\n\n**Available templates:** `android`, `ansible`, `astro`, `aws`, `bun`, `deno`, `django`, `docker`, `dotnet`, `elixir`, `expo`, `fastapi`, `flutter`, `git`, `go`, `hugo`, `java-gradle`, `java-maven`, `kubernetes`, `laravel`, `monorepo`, `nestjs`, `nextjs`, `node`, `python`, `rails`, `react`, `rust`, `svelte`, `tauri`\n\n---\n\n### `xeq validate`\n\nChecks all scripts for errors without running anything.\n\n```bash\nxeq validate\nxeq validate --global\n```\n\nCatches undefined variables, missing nested scripts, circular dependencies, invalid shells, parallel conflicts, and more.\n\n---\n\n### `xeq list`\n\nShows all scripts in your `xeq.toml` - names, descriptions, and commands.\n\n```bash\nxeq list\nxeq list --global\n```\n\n---\n\n### `xeq config [path]`\n\nSaves a `xeq.toml` path globally so you can run it from anywhere.\n\n```bash\nxeq config ~/my-scripts/xeq.toml   # save once\nxeq config                          # open saved file in your editor\n```\n\n---\n\n### `xeq toml`\n\nPrints the full TOML format reference.\n\n---\n\n### Aliases\n\n| Command        | Alias   |\n| -------------- | ------- |\n| `xeq run`      | `xeq r` |\n| `xeq config`   | `xeq c` |\n| `xeq init`     | `xeq i` |\n| `xeq validate` | `xeq v` |\n\n---\n\n## TOML Format\n\nEach script needs at minimum a `run` array:\n\n```toml\n[my-script]\ndescription = \"What this script does\"\ndir = \"./my_app\"\nparallel_threads = 4\noptions = [\"quiet\"]\nrun = [\n    \"command one\",\n    \"command two\"\n]\n```\n\n- `run` - required, commands to execute in order\n- `description` - optional, shown in `xeq list`\n- `dir` - optional, working directory (absolute or relative)\n- `parallel_threads` - optional, enables parallel execution with a set thread count\n- `options` - optional, baked-in flags. see [Script Options](#1-script-options)\n\nScript names are case-sensitive. `Build` and `build` are different scripts.\n\n---\n\n## Features\n\n### 1. Script Options\n\nBake default behavior into a script so you don't have to pass flags every time:\n\n```toml\n[build]\noptions = [\"quiet\", \"continue_on_err\"]\nrun = [\"cargo build\", \"cargo test\"]\n```\n\n**Available options:** `quiet`, `clear`, `continue_on_err`, `allow_recursion`, `summary`, `allow_empty_vars`\n\nCLI flags toggle script options. If `quiet` is baked in and you pass `--quiet`, it turns quiet off for that run.\n\n```bash\nxeq run build          # quiet ON  (from TOML)\nxeq run build --quiet  # quiet OFF (toggled)\n```\n\n---\n\n### 2. Variables\n\nDefine reusable values in a `[vars]` block and reference them with `{{@varname}}`:\n\n```toml\n[vars]\nimage = \"myapp:latest\"\nenv = \"development\"\n\n[build]\nrun = [\"docker build -t {{@image}} .\"]\n\n[start]\nrun = [\"APP_ENV={{@env}} npm start\"]\n```\n\n**Local variables** override global ones for a specific script:\n\n```toml\n[vars]\nimage = \"myapp:latest\"\n\n[build]\nvars.image = \"myapp:build\"\nrun = [\"docker build -t {{@image}} .\"]   # uses \"myapp:build\"\n\n[push]\nrun = [\"docker push {{@image}}\"]          # uses \"myapp:latest\"\n```\n\n**Override at runtime** with `--args`:\n\n```bash\nxeq run build --args image=myapp:hotfix\n```\n\n**Fallback values** - use `|` to provide a default if a variable isn't set:\n\n```toml\n[build]\nrun = [\"docker build -t {{@image | myapp:latest}} .\"]\n```\n\n**Resolution order:** `--args` → local vars → global vars → fallback\n\n\u003e If a variable isn't defined and no fallback is set, xeq exits with an error. Pass `--allow-empty-vars` or add `allow_empty_vars` to options to skip this.\n\n---\n\n### 3. Arguments\n\nUse positional placeholders `{{1}}`, `{{2}}` for values that change every run:\n\n```toml\n[create]\nrun = [\n    \"npm create vite@latest {{1}} -- --template {{2}}\",\n    \"cd {{1}}\",\n    \"npm install\"\n]\n```\n\n```bash\nxeq run create --args my-app react\n# {{1}} = my-app\n# {{2}} = react\n```\n\nMix named and positional args:\n\n```bash\nxeq run deploy --args env=production my-app\n```\n\n\u003e Missing arguments cause an error. Use `--allow-empty-vars` to skip this.\n\n---\n\n### 4. Environment Variables\n\nReference environment variables with `{{$VARNAME}}`:\n\n```toml\n[deploy]\nrun = [\"deploy --token {{$API_TOKEN}} --env {{$DEPLOY_ENV}}\"]\n```\n\nxeq loads a `.env` file from the current directory automatically:\n\n```bash\n# .env\nAPI_TOKEN=abc123\nDEPLOY_ENV=production\n```\n\nPass `--no-env` to skip loading `.env`.\n\n\u003e Missing env vars cause an error. Use `--allow-empty-vars` to skip this.\n\n---\n\n### 5. Nested Scripts\n\nCall other scripts from within a script using the `xeq:` prefix:\n\n```toml\n[install]\nrun = [\"npm install\"]\n\n[build]\nrun = [\"npm run build\"]\n\n[deploy]\nrun = [\n    \"xeq:install\",\n    \"xeq:build\",\n    \"npm run deploy\"\n]\n```\n\nRunning `xeq run deploy` runs `install` and `build` first, in order.\n\n\u003e xeq detects circular dependencies and exits. Add `allow_recursion` to options if you intentionally need a script to call itself.\n\n---\n\n### 6. Parallel Execution\n\nRun all commands in a script at the same time:\n\n```toml\n[check]\nparallel_threads = 4\nrun = [\n    \"cargo test\",\n    \"cargo clippy\",\n    \"cargo fmt --check\"\n]\n```\n\nUse `-p` to toggle parallel mode from the CLI, or `-p \u003cthreads\u003e` to override the thread count:\n\n```bash\nxeq run check         # uses parallel_threads from TOML\nxeq run check -p      # uses logical CPU count\nxeq run check -p 8    # uses 8 threads\n```\n\n\u003e Scripts with `cd` commands or `xeq:` calls cannot run in parallel. `xeq validate` catches this.\n\n---\n\n### 7. Global Configuration\n\nSave a `xeq.toml` globally to run scripts from any directory:\n\n```bash\nxeq config ~/my-scripts/xeq.toml   # save once\nxeq run git-cleanup --global        # run from anywhere\nxeq list --global                   # list global scripts\n```\n\n---\n\n### 8. Run Summary\n\nPass `--summary` to see every command and how long it took:\n\n```bash\nxeq run build --summary\n```\n\n```\ncommand                        time   status\n--------------------------------------------------\ncargo test                     1.39s  succeeded\ncargo clippy                   0.80s  succeeded\ncargo fmt                      0.26s  succeeded\n```\n\n---\n\n### 9. Events\n\nRun additional commands when a script succeeds or fails:\n\n```toml\n[build]\nrun = [\"cargo test\", \"cargo build\"]\non_success = [\"echo build passed\"]\non_error = [\"echo build failed\"]\n```\n\n**Rules:**\n- Events are ignored during parallel execution\n- Events disable the run summary\n- Events cannot be combined with `continue_on_err`\n\n---\n\n### 10. Custom Shells\n\nSet a shell at the file level to run all commands with:\n\n```toml\nshell = \"zsh\"\n\n[build]\nrun = [\"cargo build\", \"cargo test\"]\n```\n\n**Available shells:** `sh`, `bash`, `zsh`, `fish`, `cmd`, `powershell`\n\nDefaults to `sh` on Linux/macOS and `cmd` on Windows.\n\n---\n\n## Examples\n\nThe [`examples/`](./examples) folder has ready-to-use TOML files for common workflows.\n\n| File                  | Description                                 | Features Used                             |\n| --------------------- | ------------------------------------------- | ----------------------------------------- |\n| `react-tailwind.toml` | Scaffold and run a React + Tailwind project | variables, cd operators                   |\n| `nextjs.toml`         | Next.js project setup and pipeline          | nested scripts, variables                 |\n| `rust-project.toml`   | Rust checks, build and publish              | parallel, nested scripts                  |\n| `docker.toml`         | Docker image and container management       | variables, nested scripts                 |\n| `git-workflow.toml`   | Common git operations                       | variables, arguments                      |\n| `nested-scripts.toml` | CI pipeline from reusable pieces            | nested scripts                            |\n| `env-vars.toml`       | Deploy and notify using env vars            | `{{$VAR}}`, nested scripts                |\n| `python-project.toml` | Virtualenv, checks and PyPI publish         | parallel, nested scripts, variables       |\n| `database.toml`       | Migrations, seed, dump and restore          | env vars, arguments, nested scripts       |\n| `monorepo.toml`       | Multi-package frontend workspace            | parallel, variables, nested scripts       |\n| `aws-deploy.toml`     | ECR push and ECS deploy pipeline            | env vars, nested scripts                  |\n| `go-project.toml`     | Go build, test and cross-compile            | parallel, nested scripts, variables       |\n| `arguments.toml`      | Positional and named arg patterns           | arguments, variables                      |\n| `script-options.toml` | Flag toggle mechanic demonstrations         | options, parallel, quiet, continue_on_err |\n\n---\n\n## How It Works\n\n- xeq reads `xeq.toml` from the current directory, or a globally saved path with `--global`\n- Commands run through `sh -c` on Linux/macOS and `cmd /C` on Windows by default\n- `cd` commands update the working directory for all subsequent commands in that script\n- Variables resolve in order: `--args` → local vars → global vars → fallback\n- `.env` is loaded automatically before any script runs\n- Script names are case-sensitive\n\n---\n\n## License\n\nMIT - [LICENSE](LICENSE)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopmr0%2Fxeq","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopmr0%2Fxeq","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopmr0%2Fxeq/lists"}