Ark CLI Developer Guide

Conventions for developing the Ark CLI and commands. Ark provides two CLIs: ark (Node.js) for general-purpose interactive use with non-interactive mode for scripting, and fark (Go) optimized for resource management and low latency. Both are located in tools/.

Design Conventions

Ark’s CLI design draws from kubectl and argo, aiming to make the experience familiar for users.

Kubernetes kubectl provides resource-oriented operations:


kubectl get pods                    # List resources
kubectl get pods -o json            # JSON output
kubectl describe pod my-pod         # Detailed view
kubectl get pods --timeout=30s      # With timeout

Argo Workflows manages workflow execution and monitoring:


argo list                    # List workflows
argo list --running          # Filter by status
argo get my-workflow         # Get workflow details
argo logs my-workflow        # View logs
argo submit workflow.yaml    # Submit workflow (interactive by default)
argo list -o wide            # Extended output

Both use the default kubeconfig context for Kubernetes connections.

Command Conventions

Global level commands can be created to manage the Ark platform - these commands should be created judiciously. They are interactive by default but can also be scripted.


ark install                  # Install platform (interactive)
ark install --yes            # Non-interactive (for scripts)
ark status                   # Check system health
ark dashboard                # Open dashboard
ark completion               # Shell completion

Resource level commands follow the pattern: ark <resource> <action> [name] [options]


# Resources: models, agents, teams, tools, evaluation
# Common verbs: list (default), create, status, query, delete, watch
 
ark models                          # List models
ark models create default           # Create model
ark agents query weather "msg"      # Query agent
ark models status default           # Check model health

Note: watch is not yet implemented but will likely be added soon.

Shorthand options can occasionally be offered if they provide clearer scripting or interactive syntax:


# Standard resource / verb / noun syntax.
ark models query default "What is 2+2?"
 
# Shorthand verb syntax, more natural for some of the more essential commands.
ark query model/default "What is 2+2?"
 
# Sorthand for calling evaluation
ark evaluation ark-evaluator --input "What is 2+2?" --output "5"
 
# Chaining query and evaluation example
ark query model/default "What is 2+2?" -o name | ark evaluation ark-evaluator

Note that the target format is <type>/<name> (e.g., agent/weather, team/my-team), as per the Ark APIs. Consider supporting @latest as a convenience alias for the most recently created resource, similar to argo logs @latest. This feature is not yet implemented but will likely be added soon.

Parameter Conventions

Following kubectl/argo patterns. Essential parameters:

Flag	Purpose	Example
`-o, --output`	Output format (json, yaml, text)	`ark models -o json`
`--timeout`	Operation timeout	`ark agents query weather "msg" --timeout 30s`
`@latest`	Latest resource alias (planned)	`ark queries logs @latest`

Exit Code and Error Handling Conventions

Four main status codes are used:

Code	Meaning	When to Use
`0`	Success	Command completed
`1`	CLI Error	Invalid arguments, config issues
`2`	Operation Error	Backend failure, resource error
`3`	Timeout	Operation exceeded time limit

This helps scripts distinguish between usage errors, operational failures, timeouts, and evaluation failures. Error details are printed by the CLI.

Query operations return exit code 2 when execution fails and 3 on timeout, making error handling in scripts straightforward. This behavior aligns with Argo Workflows’ --wait flag pattern (see argoproj/argo-workflows#1008 ).

Example handling exit codes:


if ! ark agents query weather "What's the weather?"; then
   echo "Query failed with exit code $?"
fi

Output Conventions

Tables

Text format output (-o text) uses tables with the following structure:

Column headers in uppercase
Data rows below the header
Columns separated by 2 blank spaces

Status values use color coding to convey state information:

Green indicates successful completion
Blue indicates in-progress operations
Red indicates errors or failures
Yellow indicates pending or undefined states

Example table output:

NAME     DESCRIPTION          STATUS
entry-1  entry description 1  success
entry-2  entry description 2  running
entry-3  entry description 3  fail
entry-4  entry description 4  initializing

Empty tables are highlighted with a warning message:

! warning: no entries found

Interactive Conventions

Colors and progress indicators are enabled by default in interactive terminals and automatically disabled when output is piped, NO_COLOR is set, or running in non-TTY environments. Default output is human-readable text. Use -o json for machine-readable output.

Ark uses chalk for terminal colors and ora, which automatically respect TTY and non-TTY environments.

The ark chat offers full interactive experience inspired by Claude Code, and uses Ink .

Debugging Conventions

Enable debug logging using the DEBUG environment variable. The Node.js debug module is used:


# Enable all ark debug output
DEBUG=ark:* ark status