Skip to Content

CLI Tools

ARK provides two command-line tools for different use cases.

Overview

fark - Fast Agentic Runtime Kit

The primary tool for querying agents and teams, plus CRUD operations on ARK resources.

ark - ARK Management Interface

Interactive dashboard and system status monitoring tool.

fark

fark is the primary CLI tool for querying agents and teams, plus managing ARK resources.

Installation

# Download latest release for your platform
# Linux/macOS
curl -L "https://github.com/mckinsey/agents-at-scale-ark/releases/latest/download/fark_$(uname)_$(uname -m | sed 's/aarch64/arm64/').tar.gz" | tar xz
sudo mv fark /usr/local/bin/
 
# Windows: Download fark_Windows_x86_64.zip from releases page
 
# Verify installation
fark --help

From Source

# Clone and build from repository
git clone https://github.com/mckinsey/agents-at-scale-ark.git
cd agents-at-scale-ark
make fark-install
 
# Verify installation
fark --help

Querying Agents and Teams

Agent Queries

# Basic agent query
fark agent weather "What's the weather today?"
 
# Math calculations
fark agent math "What is 15 * 23?"
 
# Location queries (uses get-coordinates tool)
fark agent location "Where is Paris?"
 
# Query with file input
fark agent weather -f input.txt "Analyze this weather data"
 
# Query with session and conversation management (requires memory service)
fark agent weather "What's the weather in NYC?" --session-id weather-session --conversation-id weather-conv
fark agent weather "How about tomorrow?" --session-id weather-session --conversation-id weather-conv

Team Queries

# Basic team query
fark team team-seq "Process this request"
 
# Query team with multiple agents
fark team team-seq "Calculate 2+2 and explain the result"

Query Management

# List all queries
fark query
 
# Trigger existing query
fark query weather-query
 
# Trigger with new input
fark query weather-query "What's the weather in London?"

Resource Management

Listing Resources

# List all agents
fark get agent
 
# List all teams
fark get team
 
# List all models
fark get model
 
# List all tools
fark get tool
 
# Get specific resource details
fark get agent weather

Creating Resources

# Create agent from file
fark create agent my-agent -f samples/agents/math.yaml
 
# Create agent with prompt
fark create agent my-math --prompt "You're an agent helping with calculations" --model default
 
# Create agent with tools
fark create agent my-location --prompt "Help with location queries" --tools get-coordinates

Updating Resources

# Update agent from file
fark update agent math -f updated-agent.yaml
 
# Update agent prompt
fark update agent math --prompt "You're an advanced mathematical assistant"

Deleting Resources

# Delete specific agent
fark delete agent math
 
# Delete team
fark delete team team-seq

Output Options

# JSON output
fark agent math "What is 5 + 3?" --json
 
# Verbose logging (shows token usage)
fark agent math "What is 5 + 3?" --verbose
 
# Silent mode (suppress event logging)
fark agent math "What is 5 + 3?" --silent

Server Mode

fark can also run as an HTTP server providing REST API endpoints:

# Start server on default port 8080
fark server
 
# Start server on custom port
fark server --port 9090

Shell Completion

# Install completion for zsh
fark completion zsh > ~/.fark-completion
echo "source ~/.fark-completion" >> ~/.zshrc
source ~/.zshrc
 
# Install completion for bash
fark completion bash > /etc/bash_completion.d/fark

ark CLI

ark provides an interactive dashboard and system monitoring capabilities.

Installation

# Build and install from repository root
make ark-cli-install
 
# Verify installation
ark --help

Interactive Menu

Launch the interactive menu interface:

ark

System Status

Check the status of ARK services and components:

# Check overall system status
ark status

ark mcp auth

Drive interactive OAuth flows for MCP servers whose status.authorization.state is Required. The CLI port-forwards to ark-api, asks it to start the flow, opens the IdP authorize URL in the user’s browser, and polls until the IdP redirects back to ark-api with the authorization code. ark-api performs the token exchange and writes the result to the Kubernetes Secret named in spec.authorization.tokenSecretRef.

The CLI never reads or writes Secrets directly — every Kubernetes resource operation goes through ark-api endpoints. The only kubectl shell-out is port-forward against the ark-api Service, the same as every other ark command.

Login

ark mcp auth login <server-name>
FlagDescription
--namespace, -nMCPServer namespace. Defaults to the active kubeconfig context’s namespace, then default.
--forceBypass the preflight refusal when already Authorized and force fresh client registration.
--no-openPrint the authorization URL but do not invoke the system browser.
--timeout <duration>Maximum time to wait for the user to complete the flow. Go-duration string (e.g. 60s, 5m, 1h). Default 5m.
--scope <scope>Space- or comma-separated list of OAuth scopes to request.

Successful exit prints authorized (token expires at <RFC 3339>). Failure exits non-zero with a single mcp auth failed: <reason> line — the IdP’s OAuth error is surfaced verbatim.

Logout

ark mcp auth logout <server-name>
FlagDescription
--namespace, -nMCPServer namespace. Same fallback as login.
--keep-clientPreserve the cached client_id / client_secret so the next login skips DCR.
--delete-secretDelete the referenced Secret entirely instead of clearing keys. Mutually exclusive with --keep-client.

The default behaviour clears access_token, refresh_token, expires_at, client_id, and client_secret. Logout is idempotent — calling it against a server with no Secret returns logout: nothing to clear and exits zero. A missing MCPServer exits non-zero with MCPServer not found.

For operator-side configuration (the callback URL, RBAC, port-forward recipe), see MCP OAuth Callback.

Common Use Cases

Development Workflow

# Create and test an agent
fark create agent test-math --prompt "You are a helpful math assistant"
fark agent test-math "What is 2 + 2?"
 
# Update and retest
fark update agent test-math --prompt "You are an advanced mathematical assistant"
fark agent test-math "Calculate the square root of 16"
 
# Clean up
fark delete agent test-math

Production Monitoring

# Check system health
ark status
 
# Monitor specific resources
fark get agent
fark get team
 
# Query agents with structured output
fark agent weather "What's the weather?" --json

k9s

k9s is a terminal-based UI for Kubernetes that lets you interactively manage and work with your cluster. It provides a visual interface to navigate, inspect, and modify Kubernetes resources including ARK resources such as agents, teams, models, and queries without memorizing complex kubectl commands.

Installation

k9s can be installed separately and launched from your terminal. First, ensure your development environment is running:

# start development environment
devspace dev
# launch k9s
k9s

Useful Commands

CommandDescription
?Show help and all available commands
:crdsShow all custom resource definitions (CRDs) including agents, models, teams
:agentsShow all agents in the cluster
:modelsShow all models in the cluster
:teamsShow all teams in the cluster
:podsShow all pods
:svcShow all services
:deployShow all deployments
dDescribe the selected resource
Shift+JJump to owner (eg Agent → MCP Server)
Shift+ASort resources by age
eEdit the selected resource
Ctrl+DDelete the selected resource
lView logs for the selected pod
sShell into the selected pod
/Filter resources by name
EscapeGo back to previous view

Navigate to any resource type by typing : followed by the resource name. Use the arrow keys to select resources and the commands above to interact with them.

kubectl

kubectl is the command-line tool for interacting with Kubernetes clusters. It’s essential for managing ARK resources and troubleshooting applications.

Installation

# macOS
brew install kubectl
 
# Linux
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
chmod +x kubectl
sudo mv kubectl /usr/local/bin/
 
# Windows
choco install kubernetes-cli

Basic Commands

View ARK Resources

# List all pods in the default namespace
kubectl get pods
 
# List all ARK custom resources
kubectl get queries,agents,teams,models
 
# Get detailed information about a specific query
kubectl describe query my-query

Logs and Debugging

# View logs from a pod
kubectl logs pod-name
 
# Follow logs in real-time
kubectl logs -f pod-name
 
# Execute commands in a running container
kubectl exec -it pod-name -- /bin/bash

Managing Resources

# Apply an ARK configuration
kubectl apply -f my-query.yaml
 
# Delete a resource
kubectl delete query my-query
 
# Edit a resource in-place
kubectl edit query my-query

Working with Namespaces

# List all namespaces
kubectl get namespaces
 
# Switch context to a specific namespace
kubectl config set-context --current --namespace=my-namespace

Useful Aliases

Add these to your shell configuration:

alias k=kubectl
alias kgp='kubectl get pods'
alias kgs='kubectl get svc'
alias kgn='kubectl get nodes'
Last updated on
Quickstart