Local Development

The ark CLI lets you run, test, and debug pipelines entirely locally — no Kubernetes cluster, no Redis, no operator. The same YAML files deploy unchanged to a cluster.

The iteration loop

Edit team.yaml
    │
    ▼
ark run team.yaml --provider mock --watch
    │  (instant, no API calls, validates wiring)
    ▼
ark run team.yaml --provider openai --watch   ← real model
    │  (real LLM, iterate on prompts)
    ▼
ark validate team.yaml                         ← sanity check before deploy
    │
    ▼
kubectl apply -f team.yaml

Step 1: Validate structure with mock

Before writing a single token, confirm your DAG wiring is correct:

ark run team.yaml --provider mock --watch --input topic="test"

The mock provider returns deterministic placeholder responses instantly. This validates:

All dependsOn chains are correct
Template expressions (,) resolve
Step order makes sense

If a template expression fails to resolve, ark run exits with an error pointing to the problematic step.

Step 2: Iterate on prompts with a real model

Once the wiring is correct, connect to a real model:

With Ollama (recommended — no API cost):

ollama pull llama3.2

OPENAI_BASE_URL=http://localhost:11434/v1 \
OPENAI_API_KEY=ollama \
  ark run team.yaml --provider openai --watch --input topic="your topic"

With OpenAI or Anthropic:

OPENAI_API_KEY=sk-... ark run team.yaml --watch --input topic="your topic"
ANTHROPIC_API_KEY=sk-ant-... ark run team.yaml --watch --input topic="your topic"

The --watch flag streams each step’s status and output as it completes:

  researcher       [running]
  researcher       [done]    1842 tokens  4.2s
    └─ Key facts about distributed consensus: Paxos requires...
  writer           [running]
  writer           [done]    624 tokens  2.1s
    └─ Distributed consensus algorithms are fundamental to...

Flow Succeeded in 6.3s — total: 2466 tokens

Step 3: Override inputs on the command line

Test different inputs without editing YAML:

ark run team.yaml --provider mock --watch \
  --input topic="consensus algorithms" \
  --input style="academic"

Each --input flag sets a key in ``.

Step 4: Capture output

Write the final output to a file:

ark run team.yaml --provider openai \
  --input topic="distributed systems" \
  --output ./result.json

For machine-readable output (CI-friendly):

ark run team.yaml --provider mock --output json

{
  "status": "succeeded",
  "duration_ms": 3100,
  "total_tokens": 2154,
  "steps": [
    { "name": "researcher", "status": "succeeded", "tokens": 1842, "output": "..." },
    { "name": "writer", "status": "succeeded", "tokens": 312, "output": "..." }
  ]
}

Step 5: Validate before deploy

ark validate team.yaml

  DAG          ok  (3 steps, 0 cycles)
  Agents       ok  (researcher, writer, editor)
  Schema       ok
Validation passed.

ark validate checks DAG structure (cycle detection), dependsOn references, if: expressions, and JSON schema compliance — without making any model calls.

Debugging with traces

Add --trace to collect an in-memory span tree:

ark run team.yaml --provider openai --trace

Flow succeeded in 9.1s — 1,516 tokens

arkonis.task [9.1s]
  ├─ arkonis.llm.call [4.2s]  researcher  in=1,204 out=312
  └─ arkonis.llm.call [2.1s]  writer  in=312 out=88

This shows exactly how long each LLM call took and how many tokens it used — useful for identifying slow or expensive steps.

Testing conditional logic

Test that if: conditions behave as expected:

# Should skip the "escalate" step
ark run team.yaml --provider mock --watch --input severity="low"

# Should run the "escalate" step
ark run team.yaml --provider mock --watch --input severity="critical"

With --provider mock, the mock output contains the step name and input — you can craft mock responses that set specific outputSchema fields by providing a custom mock config (see ark run --help).

CI integration

Run in CI without any credentials:

# In your CI pipeline
ark validate team.yaml
ark run team.yaml --provider mock --output json | jq '.status == "succeeded"'

Exit code is 0 on success, 1 on failure — works natively with CI pass/fail gates.

Differences from the cluster operator

Feature	ark CLI	Cluster operator
Pipeline mode	Yes	Yes
Dynamic delegation mode	No	Yes
Redis task queue	No (in-process)	Yes
Replica management	No	Yes
Semantic health checks	No	Yes
ArkEvent triggers	No	Yes
ArkMemory	No	Yes

Use the CLI for development, testing, and one-off runs. Deploy to the operator for production workloads.