{"id":16394,"library":"httpyac","title":"httpyac CLI Client","description":"httpYac (current version 6.16.7) is a robust command-line interface (CLI) and Node.js package designed for testing and automating API interactions using `.http` and `.rest` files. It supports an extensive range of protocols including HTTP, REST, GraphQL, WebSocket, gRPC, RabbitMQ (AMQP), EventSource, and MQTT, offering a versatile solution beyond traditional HTTP-only clients. The project maintains an active development pace, with frequent minor releases (e.g., 6.16.x) primarily focusing on bug fixes, performance improvements, and feature enhancements, as demonstrated by its detailed changelog entries. Its core strength lies in enabling developers to define complex request sequences, variables, and test assertions directly within `.http` files, providing a file-based alternative to GUI tools like Postman or Insomnia. A key differentiator is its extensibility and the fact that it ships with comprehensive TypeScript types, facilitating programmatic integration despite its primary CLI orientation. It requires Node.js version 18 or higher to run effectively, ensuring compatibility with modern JavaScript runtime features. The tool also boasts a popular VS Code extension, making it a powerful choice for developers working within that ecosystem.","status":"active","version":"6.16.7","language":"javascript","source_language":"en","source_url":"https://github.com/AnWeber/httpyac","tags":["javascript","HTTP","REST","GraphQL","Intellij Http Client","Postman","Soap","gRPC","RabbitMQ","typescript"],"install":[{"cmd":"npm install httpyac","lang":"bash","label":"npm"},{"cmd":"yarn add httpyac","lang":"bash","label":"yarn"},{"cmd":"pnpm add httpyac","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"httpyac is an ESM-first package designed for Node.js environments. Prefer ES module imports. This is a primary function for programmatic execution of .http files.","wrong":"const executeFile = require('httpyac')","symbol":"executeFile","correct":"import { executeFile } from 'httpyac'"},{"note":"This is a TypeScript type definition for configuration options. Use 'import type' for clarity and to ensure it's removed from the compiled JavaScript bundle.","wrong":"import { HttpYacConfig } from 'httpyac'","symbol":"HttpYacConfig","correct":"import type { HttpYacConfig } from 'httpyac'"},{"note":"The 'processor' object provides hooks and utilities for custom request handling, transformation, or extension; ensure correct casing as it is not a class constructor.","wrong":"import { Processor } from 'httpyac'","symbol":"processor","correct":"import { processor } from 'httpyac'"}],"quickstart":{"code":"// requests.http (e.g., in a file named 'example.http')\n\n@user = testuser\n@password = secretpassword\n\n// A basic GET request to a public API endpoint\nGET https://httpbin.org/basic-auth/{{user}}/{{password}}\nAuthorization: Basic {{user}} {{password}}\nAccept: application/json\n\n###\n\n// A POST request with a JSON body and an environment variable\n@apiBaseUrl = https://httpbin.org\n\nPOST {{apiBaseUrl}}/post\nContent-Type: application/json\n\n{\n  \"message\": \"Hello from httpyac!\",\n  \"timestamp\": \"{{$isoTimestamp}}\",\n  \"env_data\": \"{{$env.MY_APP_DATA ?? 'default'}}\"\n}\n\n// JavaScript/TypeScript programmatic runner (e.g., 'run.ts')\nimport { executeFile } from 'httpyac';\nimport path from 'path';\n\nasync function runHttpYacFile() {\n  // Path to your .http file\n  const filePath = path.resolve(__dirname, './example.http');\n\n  // Set an environment variable for the run (optional)\n  process.env.MY_APP_DATA = 'important_value';\n\n  try {\n    const results = await executeFile(filePath, {\n      // Options for execution\n      log: console, // Use console for logging output\n      all: true,    // Execute all requests in the file\n      // Pass environment variables specific to this run\n      environments: {\n        development: { // An environment named 'development'\n          token: 'my-auth-token'\n        }\n      },\n      // Optionally specify a subset of requests by name or line number\n      // name: 'POST request with a JSON body',\n      // line: 10 // Line number of the request start\n    });\n\n    console.log('\\n--- Execution Summary ---');\n    results.forEach((exchange, index) => {\n      console.log(`Request ${index + 1}: ${exchange.request.url}`);\n      console.log(`  Status: ${exchange.response?.statusCode} ${exchange.response?.statusMessage}`);\n      if (exchange.response?.body) {\n        console.log(`  Body: ${exchange.response.body.toString().substring(0, 100)}...`);\n      }\n      if (exchange.testResults?.length) {\n        console.log('  Tests:');\n        exchange.testResults.forEach(test => console.log(`    - ${test.name}: ${test.result ? 'Passed' : 'Failed'}`));\n      }\n      if (exchange.error) {\n        console.error(`  Error: ${exchange.error.message}`);\n      }\n    });\n  } catch (error) {\n    console.error('An unexpected error occurred during execution:', error);\n  }\n}\n\nrunHttpYacFile();","lang":"typescript","description":"This quickstart demonstrates how to create a basic `.http` file with variables and multiple requests, and then execute it programmatically using the `httpyac` library in a TypeScript environment, logging the results."},"warnings":[{"fix":"Review all test suites utilizing `@ref` directives. Modify dependent requests or test logic to explicitly check the results of referenced requests if their success is critical for subsequent steps, as the execution flow may no longer halt automatically.","message":"As of `v6.16.3`, the behavior of `@ref` (referenced HTTP regions) has changed significantly. Negative test results from a reference request no longer automatically stop the dependent request, and errored references are not executed multiple times if referenced repeatedly. This alters the flow of complex test suites.","severity":"breaking","affected_versions":">=6.16.3"},{"fix":"Ensure that all tests within a request region succeed if subsequent requests or scripts depend on variables derived from its named response. Update test assertions to pass consistently or refactor dependencies.","message":"Since `v6.16.2`, named response objects, which are often used to propagate variables, are only populated if *all* associated test results for that request are valid. Previously, named responses might have been available even with some test failures, which could lead to unexpected behavior in scripts relying on those variables.","severity":"breaking","affected_versions":">=6.16.2"},{"fix":"For complex programmatic use, consult the TypeScript declaration files (`.d.ts`) or the project's source code to understand available APIs. For simpler automation, consider executing the CLI directly using Node.js's `child_process` module.","message":"While `httpyac` offers programmatic access and ships TypeScript types, its primary design and documentation focus is heavily on its command-line interface and VS Code extension. Developers seeking deep programmatic integration might encounter fewer high-level abstractions or dedicated library-specific guides compared to other packages.","severity":"gotcha","affected_versions":"*"},{"fix":"Only use `--insecure` for development or testing with self-signed certificates in controlled environments. For production, ensure target servers use valid, trusted SSL certificates, or properly configure your Node.js environment to trust custom Certificate Authorities.","message":"Using the `--insecure` CLI flag (or `insecure: true` in programmatic options) bypasses SSL certificate validation. This can expose connections to man-in-the-middle attacks and is generally not recommended for production environments or sensitive data.","severity":"gotcha","affected_versions":"*"},{"fix":"Refer to the `httpyac` documentation for the exact variable resolution order. For highest precedence in CLI calls, use the `--var` flag. For programmatic usage, ensure your `environments` object is structured clearly and accounts for potential overrides.","message":"`httpyac` supports multiple mechanisms for defining variables and environments (e.g., `-e`, `--var`, `$env` placeholders, `.env` files, and `oauth2_proxy`). Understanding the precedence rules can be challenging, leading to unexpected variable values if not managed carefully.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Install `httpyac` globally using `npm install -g httpyac` (or `yarn global add httpyac`). Verify that your npm/yarn global bin directory is correctly added to your system's PATH.","cause":"The `httpyac` CLI tool is not installed globally on your system, or its installation directory is not included in your system's PATH environment variable.","error":"httpyac: command not found"},{"fix":"Install `httpyac` as a local project dependency: `npm install httpyac` or `yarn add httpyac`.","cause":"You are attempting to `import` or `require` the `httpyac` package programmatically, but it has not been installed as a local dependency in your project.","error":"Error: Cannot find module 'httpyac'"},{"fix":"Review the specified line number and the surrounding content in your `.http` file. Consult the `httpyac` documentation (or the IntelliJ HTTP Client specification which it largely follows) for correct syntax rules.","cause":"The `.http` or `.rest` file you are trying to execute contains a syntax error, such as a malformed request line, incorrect header format, or an improperly defined variable or comment.","error":"Error: Invalid HTTP file syntax at line X: ..."},{"fix":"For development or testing purposes, you can use the `--insecure` flag with the CLI (`httpyac send --insecure ...`) or set `insecure: true` in programmatic options. For production or secure environments, ensure the server has a valid, publicly trusted SSL certificate, or configure Node.js to explicitly trust your custom CA certificate.","cause":"The target server uses an SSL certificate that is not trusted by your system's (or Node.js's) default Certificate Authorities, typically a self-signed certificate or one from an internal CA.","error":"SSL Handshake failed: self-signed certificate in certificate chain"},{"fix":"This specific issue (when the state parameter is percent-encoded) was fixed in `httpyac v6.16.7`. Ensure you are using `httpyac@6.16.7` or a newer version. If the problem persists, review your OAuth2 provider's configuration and ensure callback URLs are correctly configured and match.","cause":"During an OAuth2 authorization code flow, the `state` parameter returned by the authorization server does not match the original `state` parameter generated by `httpyac`, potentially due to an encoding issue or a mismatch in the flow.","error":"OAuth2: Invalid state error with authorization code flow"}],"ecosystem":"npm"}