> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbitra.atomo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# dags

# `orbitra dags`

Commands provided by the `orbitra-dags` plugin.

## Commands

### `orbitra dags list`

```bash theme={null}
orbitra dags list [OPTIONS]
```

List the DAGs of the environment's Airflow, sorted by DAG id.

**Options:**

| Flag | Type | Required | Default | Description |
| - | - | - | - | - |
| `--name-like` | `str` | no | `None` | Only list DAGs whose id contains this text (case-insensitive). |
| `--json` | `bool` | no | `False` | Print the DAGs as machine-readable JSON to stdout instead of a table. |
| `--env` | `str` | no | `None` | Override the environment resolved by Orbitra settings. |

**Examples:**

```bash theme={null}
orbitra dags list
```

```bash theme={null}
orbitra dags list --name-like <name-like> --json
```

### `orbitra dags list-tasks`

```bash theme={null}
orbitra dags list-tasks [OPTIONS]
```

List the task instances of a DAG run, with the task ids and map indexes `logs` takes.

**Options:**

| Flag | Type | Required | Default | Description |
| - | - | - | - | - |
| `--dag-id` | `str` | yes | | The DAG id. |
| `--run-id` | `str` | yes | | The id of the run. |
| `--json` | `bool` | no | `False` | Print the task instances as machine-readable JSON to stdout instead of a table. |
| `--env` | `str` | no | `None` | Override the environment resolved by Orbitra settings. |

**Examples:**

```bash theme={null}
orbitra dags list-tasks --dag-id <dag-id> --run-id <run-id>
```

```bash theme={null}
orbitra dags list-tasks --dag-id <dag-id> --run-id 3f2504e0-4f89-11d3-9a0c-0305e82c3301 --json
```

### `orbitra dags logs`

```bash theme={null}
orbitra dags logs [OPTIONS]
```

Read the log of a task instance of a DAG run.

**Options:**

| Flag | Type | Required | Default | Description |
| - | - | - | - | - |
| `--dag-id` | `str` | yes | | The DAG id. |
| `--run-id` | `str` | yes | | The id of the run. |
| `--task-id` | `str` | yes | | The task id; `orbitra dags list-tasks` lists them. |
| `--try` | `int` | no | `None` | The try to read. If omitted, reads the current try. |
| `--map-index` | `int` | no | `-1` | The map index of a mapped task instance; -1 for a task that is not mapped. |
| `--json` | `bool` | no | `False` | Print the log lines as machine-readable JSON to stdout instead of a table. |
| `--env` | `str` | no | `None` | Override the environment resolved by Orbitra settings. |

**Examples:**

```bash theme={null}
orbitra dags logs --dag-id <dag-id> --run-id <run-id> --task-id <task-id>
```

```bash theme={null}
orbitra dags logs --dag-id <dag-id> --run-id 3f2504e0-4f89-11d3-9a0c-0305e82c3301 --task-id <task-id> --try 100 --map-index 100 --json
```

### `orbitra dags runs`

```bash theme={null}
orbitra dags runs [OPTIONS]
```

List the runs of a DAG, most recent first.

**Options:**

| Flag | Type | Required | Default | Description |
| - | - | - | - | - |
| `--dag-id` | `str` | yes | | The DAG id. |
| `--limit` | `int` | no | `10` | The maximum number of runs to return, from 1 to 100. |
| `--state` | `list` | no | `None` | Only list runs in this state: queued, running, success or failed. Repeat to accept several: --state failed --state running. |
| `--start-time` | `datetime` | no | `None` | Only list runs that started at or after this time. A time without a timezone is read as UTC. |
| `--end-time` | `datetime` | no | `None` | Only list runs that started at or before this time. A time without a timezone is read as UTC. |
| `--json` | `bool` | no | `False` | Print the runs as machine-readable JSON to stdout instead of a table. |
| `--env` | `str` | no | `None` | Override the environment resolved by Orbitra settings. |

**Examples:**

```bash theme={null}
orbitra dags runs --dag-id <dag-id>
```

```bash theme={null}
orbitra dags runs --dag-id <dag-id> --limit 100 --state <state> --start-time <start-time> --end-time <end-time> --json
```

### `orbitra dags status`

```bash theme={null}
orbitra dags status [OPTIONS]
```

Read the current state of a DAG run.

**Options:**

| Flag | Type | Required | Default | Description |
| - | - | - | - | - |
| `--dag-id` | `str` | yes | | The DAG id. |
| `--run-id` | `str` | yes | | The id of the run to inspect. |
| `--json` | `bool` | no | `False` | Print the run as machine-readable JSON to stdout instead of a table. |
| `--env` | `str` | no | `None` | Override the environment resolved by Orbitra settings. |

**Examples:**

```bash theme={null}
orbitra dags status --dag-id <dag-id> --run-id <run-id>
```

```bash theme={null}
orbitra dags status --dag-id <dag-id> --run-id 3f2504e0-4f89-11d3-9a0c-0305e82c3301 --json
```

### `orbitra dags trigger`

```bash theme={null}
orbitra dags trigger [OPTIONS]
```

Trigger a run of a DAG, optionally waiting for it to finish.

**Options:**

| Flag | Type | Required | Default | Description |
| - | - | - | - | - |
| `--dag-id` | `str` | yes | | The DAG to run. |
| `--conf` | `str` | no | `None` | A JSON object passed as the run configuration (`dag_run.conf`), value types as written. |
| `--wait` | `bool` | no | `False` | Wait for the run to end and render it; exits with 1 when it ends `failed`. |
| `--timeout` | `float` | no | `None` | When waiting, the maximum number of seconds to wait. If omitted, waits until the run ends. |
| `--poll-interval` | `float` | no | `5.0` | When waiting, the number of seconds between two reads of the run. |
| `--json` | `bool` | no | `False` | Print machine-readable JSON to stdout. Without --wait, prints \{"dag\_id": ..., "dag\_run\_id": ...}; with --wait, prints the finished run. |
| `--env` | `str` | no | `None` | Override the environment resolved by Orbitra settings. |

**Examples:**

```bash theme={null}
orbitra dags trigger --dag-id <dag-id>
```

```bash theme={null}
orbitra dags trigger --dag-id <dag-id> --conf '{"date": "2026-11-01", "dry_run": true}' --wait --timeout 600 --poll-interval 10
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.