The Ark CLI

ark is the command-line interface for Ark. It does three things:

• Installs and manages Ark on a Kubernetes cluster (ark install, ark status, ark uninstall).
• Inspects and authors resources — list agents, teams, models, tools, and queries; generate, export, and import them.
• Runs work — one-off queries (ark query) or an interactive chat session (ark chat).

How it works

The CLI is a thin client over two things:

• The Kubernetes API (via your current kubectl context) for cluster operations and listing/managing resources. The CLI acts in the namespace of your kube context — check it with ark cluster get.
• The ark-api service for running queries and chats. When you run a query, the CLI port-forwards to the ark-api service and talks to it over localhost. This is why query commands need a reachable cluster and kubectl access — and why, inside a pod (e.g. an Argo workflow step), you use fark instead, which calls the Kubernetes API directly.

There’s no separate login: the CLI uses whatever cluster your kubectl is pointed at.

Install and set up

# Install the CLI (requires Node.js 18+).
npm install -g @agents-at-scale/ark
 
# Check the version.
ark --version
 
# Enable shell tab-completion (add to ~/.bashrc or ~/.zshrc to persist).
eval "$(ark completion bash)"     # bash
eval "$(ark completion zsh)"      # zsh

ark config shows the effective configuration and where it came from (~/.arkrc.yaml, a project .arkrc.yaml, or ARK_* environment variables):

ark config

chat:
  streaming: true
  outputFormat: text
marketplace:
  repoUrl: https://github.com/mckinsey/agents-at-scale-marketplace
  registry: oci://ghcr.io/mckinsey/agents-at-scale-marketplace/charts
services:
  reusePortForwards: false

Command reference

Run ark <command> --help for the full options of any command. ark help lists everything.

Install and lifecycle

ark install --wait-for-ready 5m     # install everything, wait until ready
ark status                          # verify it's healthy

$ ark cluster get
context: minikube
namespace: default
type: minikube
ip: 192.168.49.2

Inspect resources

Each list command takes -o json for machine-readable output.

$ ark targets
agent/default
model/default
tool/file-gateway-read-file
...

ark queries also has subcommands for working with a single query:

ark queries get @latest -r          # just the response text of the most recent query
ark queries delete my-query
ark queries delete --all
ark queries resubmit @latest

Run work

# One-off queries against any target type.
ark query agent/my-agent "What's the refund policy?"
ark query team/research-team "Summarise the latest on EVs."
ark query model/default "Explain rate limiting in one sentence."
ark query tool/get-coordinates '{"city":"Paris"}'
 
# Output formats and conversation continuity.
ark query agent/my-agent "Hello" -o json
ark query agent/my-agent "Remember my name is Alice." --conversation-id chat-1
ark query agent/my-agent "What's my name?"  --conversation-id chat-1

-o accepts yaml, json, name, events (structured event stream), or events-pretty (human-readable event stream with color-coded reasons and expanded detail). --timeout, --session-id, and --conversation-id are also available.

ark agents query <name> <message>, ark teams query <name> <message>, and ark models query <name> <message> are equivalent shorthands for the respective target type.

Interactive chat:

ark chat                # pick a target interactively
ark chat agent/default  # chat with a specific agent or model

Create a model

ark models create is an interactive helper that creates a Model resource (and the backing API-key Secret) without writing YAML. Run it bare for prompts, or pass flags to skip them:

ark models create default                       # interactive
ark models create default \                      # non-interactive
  --type openai --model gpt-4o-mini \
  --base-url https://api.openai.com/v1 \
  --api-key "$OPENAI_API_KEY" --yes

Flags: --type (openai, azure, bedrock), --model, --base-url, --api-key, --api-version (Azure), --yes to skip confirmation.

Generate, export, import

ark generate (alias ark g) scaffolds files on disk:

ark generate project my-project    # full project: charts, CI/CD, samples
ark g agent customer-support       # an agent in the current project
ark g team research-team           # a team with a chosen strategy
 
ark export -o backup.yaml                       # everything in the namespace
ark export -t agents,teams -o agents-teams.yaml # only some types
ark import backup.yaml                           # create; errors on existing resources
ark import backup.yaml --upsert                  # create or update (kubectl apply)

Exported YAML contains desired state only. Ark removes Kubernetes runtime metadata, status, ownership references, and finalizers so the file can be applied to another cluster. Controller-generated Tools and Agents are omitted; imported MCPServer and A2AServer resources regenerate them with ownership from the destination cluster.

Marketplace

ark marketplace list
ark install marketplace/services/phoenix
ark install marketplace/agents/noah
ark uninstall marketplace/services/phoenix

Pin a version with --marketplace-version <v>. See the marketplace repo .

MCP authorization

ark mcp auth login my-server --no-open --scope "repo,read:org"
ark mcp auth logout my-server --delete-secret

Open things

Related

• Quickstart — install, verify, and create your first model and agent.
• Run queries / chat with agents and teams — what ark query / ark chat create under the hood.
• Models, Agents, Teams, Tools — the resources the CLI lists and runs.