CLI, CDK & Skills

Three ways to operate Cargo — imperative CLI commands, declarative CDK workspaces, and agent-driven Skills — all through one binary and one login.

There are three ways to drive Cargo, and they’re not separate tools — they’re three modes of the same command-line tool.

One binary, one login

Everything runs through a single binary, cargo-ai, installed and authenticated once (see the Quickstart) — every mode below reuses that same session:

• Imperative commands — cargo-ai orchestration run create, cargo-ai storage model list, … operate the platform directly.
• The CDK ships inside the same binary as cargo-ai cdk (plan, deploy, refresh, destroy). There is no separate install or login.
• Skills are prompt packages that teach an AI agent to call those same commands for you.

So “CLI vs CDK” is not a real choice of tools — the CDK is a subcommand of the CLI. The real choice is which mode fits the task.

The three modes

Mode	You write…	Reach for it when…
CLI (imperative)	one-off commands in a terminal or script	you want to run, inspect, or script a single operation — enrich a record, trigger a batch, query data, chat with an agent — without managing state
CDK (declarative)	define* TypeScript files, deployed with cargo-ai cdk deploy	you want your whole workspace as versioned, diffable code with plan/deploy and drift detection
Skills (agent-driven)	plain-English prompts to an AI agent	you want an agent to figure out the exact commands and UUIDs from a description of the goal

How they fit together

• Declarative is the default for anything you keep. Connectors, models, tools, agents, and plays belong in a CDK workspace so they’re reproducible. Start with the Quickstart.
• Imperative is for operating what you’ve deployed. Once a tool or play exists, you run and monitor it with CLI commands — one-offs, CI jobs, data pulls.
• Skills sit on top of the CLI. They’re the imperative surface, driven by an agent instead of your fingers. See Skills.

A quick rule of thumb: if you’d commit it to git, define it with the CDK. If you’d type it once, use the CLI. If you’d rather describe it than remember the flags, use Skills.

Next steps

Quickstart

Deploy your first workspace with the CDK.

Project layout

How a folder of define* files becomes a workspace.

CLI

The imperative command surface — runs, batches, queries, and more.

Skills

Drive the CLI with natural language through an AI agent.