# BlinqIO Executions CLI [![npm version](https://img.shields.io/npm/v/blinqio-executions-cli.svg)](https://npmjs.org/package/blinqio-executions-cli) [![npm downloads](https://img.shields.io/npm/dm/blinqio-executions-cli.svg)](https://npmjs.org/package/blinqio-executions-cli) > **A powerful, zero-install command-line interface for managing BlinqIO Executions** > _Create, list, trigger, and manage executions from your terminal._ --- ## 🚀 **Quick Start** ```sh npx blinqio-executions-cli ``` You'll be guided through an interactive wizard in your terminal to authenticate and perform actions. --- ## 💻 **Non-interactive Mode (for CI/CD and Power Users)** Run any action directly with command line flags—great for scripts or automations! --- ### **Create a New Execution** 1. To create using a execution template file: ```sh npx blinqio-executions-cli --token=*********** \ --mode=create \ --filePath=./path/to/execution.yaml ``` 2. To create a basic execution (one flow with one group), specify `environment`, `name`, `branch`, and `tag(s)` (single tag or comma-separated): ```sh npx blinqio-executions-cli --token=*********** \ --mode=create --env="YOUR_ENV_NAME" \ --name="NEW_EXEC_NAME" \ --branch="WHICH_BRANCH" \ --tags="tag1, tag2, tag3" CUSTOM_TEST_DATA_KEY=value ANOTHER_KEY=anotherValue ``` OR ```sh npx blinqio-executions-cli --token=*********** \ --mode=create --env="YOUR_ENV_NAME" \ --name="NEW_EXEC_NAME" \ --branch="WHICH_BRANCH" \ --tag="tag1" CUSTOM_TEST_DATA_KEY=value ANOTHER_KEY=anotherValue ``` **Note:** During creation, you can specify 2 optional arguements: - `--uploadFailedVideos=true/false` to control whether failed scenario videos should be uploaded. - `--retryCount=N` to control how many times a failing scenario should be retried before moving on. See the **Additional Optional Arguments** section below for examples. --- ### **Trigger an Execution** By Execution ID: ```sh npx blinqio-executions-cli --mode=startRun \ --token=YOUR_ACCESS_TOKEN \ --executionId=YOUR_EXECUTION_ID ``` By Execution Name: ```sh npx blinqio-executions-cli --mode=startRun \ --token=YOUR_ACCESS_TOKEN \ --executionName="Execution Name" ``` ## Additional Optional Arguements In `create` and `startRun` modes you can specify the following optional arguments to customize the execution run: ### 1. 💡 Limiting Threads You can limit the number of threads used for a particular execution run by specifying the optional `--maxThreads` flag, this will enforce an upper limit to the number of resources usable for a particular run trigger so that other runs can progress in parallel triggered by you or other team members. ```sh npx blinqio-executions-cli --mode=startRun \ --token=YOUR_ACCESS_TOKEN \ --executionName="CanaryTest" \ --maxThreads=4 ``` ### 2. 🎥 Enable Video Recordings of Failed Scenarios You can specify an optional flag: `--uploadFailedVideos=true/false` to control whether failed scenarios videos should be uploaded. These videos will be available in the BlinqIO web-app's `Reports` section for review. For example: ```sh npx blinqio-executions-cli \ --token=YOUR_ACCESS_TOKEN \ --mode=startRun \ --executionName="Regression" \ --uploadFailedVideos=true ``` ### 3. 🔄 Retry count for failed scenarios You can specify an optional flag: `--retryCount=N` to control how many times a failing scenario should be retried before moving on. For example: ```sh npx blinqio-executions-cli \ --token=YOUR_ACCESS_TOKEN \ --mode=startRun \ --executionName="Regression" \ --retryCount=2 ``` --- ### **Fetch status of any Execution (running or stopped)** By Execution instance ID: ```sh npx blinqio-executions-cli --mode=status \ --token=YOUR_ACCESS_TOKEN \ --executionInstanceId=YOUR_EXECUTION_ID ``` --- ### **Terminate a Running Execution** By Execution instance ID: ```sh npx blinqio-executions-cli --mode=stopRun \ --token=YOUR_ACCESS_TOKEN \ --executionInstanceId=EXECUTION_INSTANCE_ID ``` **Note: Terminating a running execution by name is not supported since there can be multiple running executions with the same name.** --- ## 📝 **Configuration File Example** The `--filePath` argument for creation should point to a YAML file like this: ```yaml name: Execution Name env: shop-blinq branch: main retryCount: 2 # Optional uploadFailedVideos: true # Optional customTestData: # Optional API_URL: https://api.example.com FEATURE_FLAG: true flows: - browser: chromium viewport: 1280x720 scenarioGroups: - name: Scenario Group 1 tags: - tag1 - tag2 - name: Scenario Group 2 tags: - tag3 - tag4 - browser: chromium viewport: 1280x720 scenarioGroups: - name: Scenario Group 1 tags: - tag1 - tag2 - name: Scenario Group 2 tags: - tag3 - tag4 schedule: time: 17:30 timezoneOffset: +05:30 # Timezone offset in hours, e.g., +05:30 for IST repeat: daily # Options: daily, weekly, days: # Options: the days if weekly, else empty - monday - tuesday - saturday ``` See [Full Documentation](https://www.npmjs.com/package/blinqio-executions-cli) for all schema options. --- ## 📚 **Interactive Mode Features** - **Guided prompts:** No need to remember flags. - **Template generation:** Easily generate starter YAML templates. - **CLI tables:** Visual display of current, active, and scheduled executions. - **Helpful error handling** and usage footers. --- ## 🔑 **Authentication** All commands require an **access token** (`--token=YOUR_ACCESS_TOKEN`), which you can obtain from the [BlinqIO Web App - Settings page](https://www.app.blinq.io/). --- ## 🌐 **Documentation** - CLI Docs: [blinqio-executions-cli](https://www.npmjs.com/package/blinqio-executions-cli) ↗️ --- ## ✏️ Overwriting Environment Variables You can dynamically override or provide additional environment variables for your execution when running the CLI. To do this, append your custom environment variable assignments **after all standard flags** in your CLI command. **Syntax:** ```sh npx blinqio-executions-cli [flags] ENV_VAR1=value ENV_VAR2=value ... ``` **Examples:** ```sh npx blinqio-executions-cli --token=mytoken --mode=create CUSTOM_API_URL=https://api.example.com LOG_LEVEL=debug npx blinqio-executions-cli --token=mytoken --mode=startRun --executionName='Regression Test' FEATURE_X_ENABLED=true WEBSITE_THEME=dark ``` - All custom environment variables must be written in the format `VAR_NAME=value`. - Custom environment variables should be specified _after_ CLI flags. - You can provide as many environment variables as needed. This feature is useful to adjust runtime conditions, pass secrets, or influence behavior without modifying the execution file or default environment. **Note: Support for RETRY_COUNT on the scenario level *(how many times to retry a failing scenario before declaring the group and hence the assocaited flow as failed)* is coming soon!** --- ## 🛠️ **Development & Debugging (for internal use)** - To enable debug logging for troubleshooting: ```sh npx blinqio-executions-cli --debug=true ... ``` - Or set the env variable: `DEBUG=true npx ...` --- ## 📦 **License** MIT --- ## 🙌 **Feedback & Support** - Got issues or feature requests? Open an issue on [GitHub](https://github.com/your-org/blinqio-executions-cli/issues). - Need help? Visit [BlinqIO Support](https://support.blinq.io/). --- **BlinqIO Executions CLI © [2025] BlinqIO**