# hurl-orchestra > AI first API automation testing: write each step of an API test as a small text file, and run them in the right order. ## Get started - [Install and run](https://www.estacouveflor.com/hurl-orchestra/guide/getting-started): This tutorial makes a suite of two Hurl files. The first file sends a login request and captures a token. The second file uses the token. At the end, you run the suite and read the report. - [Work with AI agents](https://www.estacouveflor.com/hurl-orchestra/how-to/work-with-ai-agents): hurl-orchestra is AI first API automation testing. It has no model inside. Its files, its commands and its results are easy for a coding agent to write, check and read. Use this procedure to let an agent such as Claude Code or Codex write and repair your API tests. ## Concepts - [The graph](https://www.estacouveflor.com/hurl-orchestra/concepts/graph): hurl-orchestra reads the frontmatter of each `.hurl` file. It then makes a directed acyclic graph (DAG). Each file is a node, and each entry in `deps` is an edge. - [Variables](https://www.estacouveflor.com/hurl-orchestra/concepts/variables): A node can give values to the nodes that need it. You declare the values in `outputs`, and you capture them in the `[Captures]` section of the Hurl file. - [Aliases](https://www.estacouveflor.com/hurl-orchestra/concepts/aliases): An alias runs one Hurl file again as a different node. Each alias has its own ID, so each alias has its own outputs. - [Failures and skips](https://www.estacouveflor.com/hurl-orchestra/concepts/failures): A node has one result. The result controls the exit code of the run and the nodes that come after it. - [Reports](https://www.estacouveflor.com/hurl-orchestra/concepts/reports): Each run writes a zip file. You can also write a CTRF report for CI. ## How-to - [Run specific files](https://www.estacouveflor.com/hurl-orchestra/how-to/run-specific-files): Use this procedure to run one file and the files that it needs. The other files in the directory do not run. - [Preview the plan](https://www.estacouveflor.com/hurl-orchestra/how-to/preview-the-plan): Use this procedure to examine the order of the nodes before a run. A dry run does not call Hurl, so you do not need Hurl on the `PATH`. - [Give flags to Hurl](https://www.estacouveflor.com/hurl-orchestra/how-to/pass-hurl-flags): Use this procedure to give Hurl options to all nodes or to one node. - [Order the nodes in a wave](https://www.estacouveflor.com/hurl-orchestra/how-to/order-a-wave): Use this procedure when independent nodes must run in a specified sequence. For example, a `delete` must not run before a `search` that needs the data. - [Retry on back pressure](https://www.estacouveflor.com/hurl-orchestra/how-to/retry-on-back-pressure): Use this procedure when a server can refuse requests under load, for example with `429 Too Many Requests` or `503 Service Unavailable`. - [Tolerate a known failure](https://www.estacouveflor.com/hurl-orchestra/how-to/tolerate-a-known-failure): Use this procedure when a node fails for a cause that you know and cannot correct now. For example, a shared test database can reach its connection limit. - [Report in GitHub Actions](https://www.estacouveflor.com/hurl-orchestra/how-to/report-in-github-actions): Use this procedure to show each Hurl request as a test in the summary of a GitHub Actions job. - [Draw the graph](https://www.estacouveflor.com/hurl-orchestra/how-to/draw-the-graph): Use this procedure to make a Mermaid diagram of the dependency graph. GitHub shows Mermaid diagrams in Markdown files. ## Reference - [Reference](https://www.estacouveflor.com/hurl-orchestra/reference/): The reference gives the names, types and default values of each option and field. - [Command line](https://www.estacouveflor.com/hurl-orchestra/reference/cli): | Option | Default | Description | |---|---|---| | `paths` | `.` | A directory with .hurl files, or one or more .hurl files. The default is the current directory. | | `--report-zip` `FILE` | `report.zip` | Write the hurl reports of all nodes to this zip file. | | `--report-ctrf` `FILE` | - | Also write a CTRF JSON report to this file. | | `--env-file` `FILE` | - | Give this variables file to each hurl call. The default is .env in the given directory, or in the current directory for files. | | `--no-deps` | - | Run only the listed .hurl files. Do not add their declared deps from the same directory. | | `--dry-run` | - | Show the execution plan. Do not run hurl. | | `--json` | - | With --dry-run, write the plan as JSON for scripts and AI agents. | | `--strict` | - | Make a failure that matches known_failures fail the run. | | `--diagram` | - | Write a Mermaid diagram of the graph. Do not run the tests. | | `--diagram-output` `FILE` | `diagram.md` | Write the diagram to this file. Use '-' for stdout. | | `--diagram-overwrite` | - | Replace the diagram file if it exists. | - [Frontmatter](https://www.estacouveflor.com/hurl-orchestra/reference/frontmatter): The frontmatter is a YAML block between two `---` lines at the start of a `.hurl` file. All fields are optional. - [Console output](https://www.estacouveflor.com/hurl-orchestra/reference/console-output): Each node writes one result line when it is complete. A failure also writes the error output of Hurl. - [CTRF report](https://www.estacouveflor.com/hurl-orchestra/reference/ctrf): `--report-ctrf` writes a [CTRF](https://ctrf.io) JSON report. The [GitHub test reporter](https://github.com/ctrf-io/github-test-reporter) and other CTRF tools can read it. ## Troubleshooting - [Troubleshooting](https://www.estacouveflor.com/hurl-orchestra/troubleshooting): Find the error in the list. Then do the steps of the solution in sequence. ## Optional - [Full documentation](https://www.estacouveflor.com/hurl-orchestra/llms-full.txt): All pages in one file.