ark validate
Validate an ArkTeam DAG structure, agent references, and schema without executing — exit codes for CI integration.
Validate a team definition without making any model calls or cluster changes.
ark validate <team.yaml> [flags]
What it checks
| Check | Description |
|---|
| DAG structure | Cycle detection using DFS across all dependsOn chains |
dependsOn references | Confirms all referenced step names exist |
canDelegate references | Confirms delegation targets are defined roles |
if: expressions | Parses conditional syntax |
loop.condition | Validates loop step configuration |
| JSON schema | Validates all spec fields against the CRD schema |
| Agent references | Verifies arkAgent names resolve (requires --check-agents and a live cluster) |
Flags
| Flag | Default | Description |
|---|
--check-agents | false | Resolve arkAgent references against a live cluster |
--kubeconfig | ~/.kube/config | Path to kubeconfig (only used with --check-agents) |
--flow | — | Select a specific team by name in a multi-team file |
Examples
# Validate a team file
ark validate team.yaml
# Validate and check agent references against the cluster
ark validate team.yaml --check-agents -n my-org
# Validate a specific team in a multi-team file
ark validate multi-team.yaml --flow research-pipeline
Example output
$ ark validate quickstart.yaml
DAG ok (2 steps, 0 cycles)
Agents ok (research, summarize)
Schema ok
Validation passed.
$ ark validate broken-team.yaml
DAG error cycle detected: summarize → research → summarize
Validation failed.
Exit codes
| Code | Meaning |
|---|
0 | Validation passed |
1 | Validation failed (error output on stderr) |
CI integration
# In your CI pipeline — fail the build if the team definition is invalid
ark validate team.yaml || exit 1
# Or simply let the non-zero exit propagate
ark validate team.yaml
See also