Cargo Storage

Cargo CLI — Storage

Data layer management: inspecting and modifying models, datasets, columns, relationships, and records, and running SQL queries against workspace storage.

See references/response-shapes.md for full JSON response structures.

See references/troubleshooting.md for common errors and how to fix them.

See references/examples/models.md for model CRUD, DDL inspection, and schema discovery examples.

See references/examples/datasets.md for dataset listing and navigation examples.

See references/examples/columns.md for column creation and management examples.

See references/examples/queries.md for storage query execute / storage query download SQL examples (WHERE, aggregations, joins, pagination, exports).

Prerequisites

See `../cargo/references/prerequisites.md` for install, login (--oauth / --token), JSON output conventions, and error shapes. Verify the session with cargo-ai whoami before running any of the commands below.

Discover resources first

Always list before inspecting or modifying.

cargo-ai storage dataset list              # all datasets (uuid, slug)
cargo-ai storage model list                # all models (uuid, name, slug, columns)
cargo-ai storage model list --dataset-uuid <uuid>   # models in a specific dataset

Retrieve in the UI: models live at app.getcargo.io/workspaces/<WORKSPACE_UUID>/models/<MODEL_UUID>. Get <WORKSPACE_UUID> from cargo-ai whoami under workspace.uuid.

Quick reference

cargo-ai storage model list
cargo-ai storage model get <model-uuid>
cargo-ai storage model get-ddl <model-uuid>
cargo-ai storage dataset list
cargo-ai storage column list --model-uuid <uuid>
cargo-ai storage relationship list --model-uuid <uuid>
cargo-ai storage record list --model-uuid <uuid>
cargo-ai storage query execute "SELECT * FROM default.companies LIMIT 10"
cargo-ai storage query download --query "SELECT * FROM default.companies"

Models

Models are structured tables in your workspace (e.g. Companies, Contacts).

# List all models
cargo-ai storage model list

# List models in a dataset
cargo-ai storage model list --dataset-uuid <uuid>

# Get a single model (includes columns)
cargo-ai storage model get <model-uuid>

# Get the DDL (full schema, table name and SQL dialect)
cargo-ai storage model get-ddl <model-uuid>
# → Useful for column discovery and SQL dialect (BigQuery vs Snowflake) before writing queries

# Create a model
cargo-ai storage model create \
  --slug contacts \
  --name "Contacts" \
  --dataset-uuid <uuid> \
  --extractor-slug <extractor-slug> \
  --config '{}'

# Update a model
cargo-ai storage model update --uuid <model-uuid> --name "New Name"

# Remove a model
cargo-ai storage model remove <model-uuid>

Querying: Use cargo-ai storage query execute "<sql>" (or storage query download --query "<sql>" for full exports) to run SQL against storage. Tables are referenced as <datasetSlug>.<modelSlug> (e.g. default.companies) and rewritten to the underlying storage table under the hood. See Query with SQL below.

Datasets

Datasets are logical groupings of models.

# List all datasets
cargo-ai storage dataset list

# Get a single dataset
cargo-ai storage dataset get <dataset-uuid>

Columns

Columns define the schema of a model.

# List columns for a model
cargo-ai storage column list --model-uuid <uuid>

# Create a column
cargo-ai storage column create \
  --model-uuid <uuid> \
  --column '{"slug":"my_column","type":"string","label":"My Column","kind":"custom"}'

# Update a column (pass the full column object — columns are identified by slug, not UUID)
cargo-ai storage column update \
  --model-uuid <uuid> \
  --column '{"slug":"my_column","type":"string","label":"Updated Label","kind":"custom"}'

# Remove a column
cargo-ai storage column remove --model-uuid <uuid> --column-slug <slug>

# Reorder a column (move to a specific index)
cargo-ai storage column reorder --model-uuid <uuid> --column-slug <slug> --to-index 2

Column types: string, number, boolean, date, object, array, vector, any.

Column kinds: custom (user-defined), computed (expression over other columns), metric (aggregated from a related model), lookup (single field pulled from a related model via a join).

Relationships

Relationships link models together (e.g. Contacts belong to Companies).

# List relationships for a model
cargo-ai storage relationship list --model-uuid <uuid>

# Set a relationship between two models
cargo-ai storage relationship set \
  --from-model-uuid <uuid> \
  --to-model-uuid <uuid>

Records

# List records in a model
cargo-ai storage record list --model-uuid <uuid>

For advanced record queries (filtering, sorting, pagination), use segmentation segment fetch from the cargo-orchestration skill.

Query with SQL

Run SQL against workspace storage with storage query execute. Tables are referenced as <datasetSlug>.<modelSlug> (e.g. default.companies) and rewritten to the underlying storage table under the hood — no DDL lookup is needed for the table name.

cargo-ai storage query execute \
  "SELECT name, domain FROM default.companies LIMIT 10"
# → { "rows": [...] } on success; non-zero exit with { "errorMessage": "..." } on error

For full exports, use storage query download — it returns a signed URL to a CSV (default) or Parquet file:

cargo-ai storage query download \
  --query "SELECT name, domain, revenue FROM default.companies ORDER BY revenue DESC"

cargo-ai storage query download \
  --query "SELECT * FROM default.companies" --format parquet

Get column slugs from storage column list --model-uuid <uuid> (or run storage model get-ddl <model-uuid> for the full schema and SQL dialect). Page through large result sets with LIMIT / OFFSET directly in the SQL.

See references/examples/queries.md for WHERE clauses, aggregations, joins, date queries, pagination, and the failure shapes returned on error.

Help

Every command supports --help:

cargo-ai storage model list --help
cargo-ai storage column create --help
cargo-ai storage relationship set --help
cargo-ai storage query execute --help
cargo-ai storage query download --help

Column examples

List columns for a model

cargo-ai storage column list --model-uuid <uuid>

Response includes uuid, slug, type, label, and position for each column.

Create a string column

cargo-ai storage column create \
  --model-uuid <uuid> \
  --column '{"slug":"website_url","type":"string","label":"Website URL","kind":"custom"}'

Create a number column

cargo-ai storage column create \
  --model-uuid <uuid> \
  --column '{"slug":"arr","type":"number","label":"Annual Recurring Revenue","kind":"custom"}'

Create a date column

cargo-ai storage column create \
  --model-uuid <uuid> \
  --column '{"slug":"last_contacted_at","type":"date","label":"Last Contacted At","kind":"custom"}'

Create a boolean column

cargo-ai storage column create \
  --model-uuid <uuid> \
  --column '{"slug":"is_customer","type":"boolean","label":"Is Customer","kind":"custom"}'

Create a computed column

Computed columns derive their value from an expression over other columns.

cargo-ai storage column create \
  --model-uuid <uuid> \
  --column '{"slug":"full_name","type":"string","label":"Full Name","kind":"computed","expression":{"kind":"jsExpression","expression":"{{record.first_name}} {{record.last_name}}","instructTo":"none","fromRecipe":false},"columnsUsed":["first_name","last_name"]}'

columnsUsed is optional but recommended for dependency tracking.

Create a metric column

Metric columns aggregate data from a related model via a relationship.

cargo-ai storage column create \
  --model-uuid <uuid> \
  --column '{"slug":"total_deals","type":"number","label":"Total Deals","kind":"metric","relationshipUuid":"<relationship-uuid>","aggregation":{"function":"count","columnSlug":"uuid"}}'

With an optional filter:

cargo-ai storage column create \
  --model-uuid <uuid> \
  --column '{"slug":"open_deals","type":"number","label":"Open Deals","kind":"metric","relationshipUuid":"<relationship-uuid>","aggregation":{"function":"count","columnSlug":"uuid"},"filter":{"conjonction":"and","groups":[{"conjonction":"and","conditions":[{"kind":"string","slug":"status","operator":"is","value":"open"}]}]}}'

Create a lookup column

Lookup columns pull a field value from a related model via a join.

cargo-ai storage column create \
  --model-uuid <uuid> \
  --column '{"slug":"company_name","type":"string","label":"Company Name","kind":"lookup","join":{"toModelUuid":"<company-model-uuid>","fromColumnSlug":"company_uuid","toColumnSlug":"uuid"},"extractColumnSlug":"name"}'

With an optional filter:

cargo-ai storage column create \
  --model-uuid <uuid> \
  --column '{"slug":"primary_contact_email","type":"string","label":"Primary Contact Email","kind":"lookup","join":{"toModelUuid":"<contacts-model-uuid>","fromColumnSlug":"uuid","toColumnSlug":"company_uuid"},"extractColumnSlug":"email","filter":{"conjonction":"and","groups":[{"conjonction":"and","conditions":[{"kind":"boolean","slug":"is_primary","operator":"isTrue"}]}]}}'

Update a column

Pass the full column object via --column. Columns are identified by slug (no UUID).

cargo-ai storage column update \
  --model-uuid <uuid> \
  --column '{"slug":"website_url","type":"string","label":"Website","kind":"custom"}'

Remove a column

cargo-ai storage column remove --model-uuid <uuid> --column-slug website_url

Reorder a column

Move a column to a specific position index (0-based).

cargo-ai storage column reorder --model-uuid <uuid> --column-slug website_url --to-index 2

Column types reference

Column kinds reference

Column slug values are used in filter conditions (see cargo-orchestration skill's references/filter-syntax.md) and in storage query execute SQL queries.

Dataset examples

List all datasets

Datasets group related models together.

cargo-ai storage dataset list

Response includes uuid, name, and slug for each dataset.

Get a specific dataset

cargo-ai storage dataset get <dataset-uuid>

List models in a dataset

cargo-ai storage model list --dataset-uuid <dataset-uuid>

Discover workspace data structure

Full flow to understand how data is organized:

# 1. List all datasets
cargo-ai storage dataset list
# → Note the dataset UUIDs and slugs

# 2. For each dataset, list its models
cargo-ai storage model list --dataset-uuid <dataset-uuid>
# → See which models (tables) belong to each dataset

# 3. Inspect a model's columns
cargo-ai storage model get <model-uuid>
# → See column slugs and types for each model

The dataset slug appears in DDL table names (e.g. datasets_default for the dataset with slug default).

Model examples

Discover all models

cargo-ai storage model list

Response includes uuid, name, slug, datasetUuid, and columns[] for each model.

Find a model by name

# List all models and filter by name in the output
cargo-ai storage model list
# → Find the entry where "name" matches what you're looking for, then extract "uuid"

Get a model's full schema

cargo-ai storage model get <model-uuid>
# → Returns the model with all columns, their types and slugs

Get the DDL (column types and SQL dialect)

storage query execute accepts <datasetSlug>.<modelSlug> (e.g. default.companies) as the table name, so you don't need the DDL just for the table name. Run model get-ddl when you need column types or the SQL dialect.

cargo-ai storage model get-ddl <model-uuid>

Example response:

{
  "ddl": "CREATE TABLE `datasets_default.models_companies` (\n  `uuid` STRING,\n  `name` STRING,\n  `domain` STRING,\n  `employee_count` INT64\n)",
  "language": "bigquery"
}

The language field tells you which SQL dialect to use.

Create a model

# First, find the dataset UUID
cargo-ai storage dataset list

# Create the model
cargo-ai storage model create \
  --slug prospects \
  --name "Prospects" \
  --dataset-uuid <dataset-uuid> \
  --extractor-slug <extractor-slug> \
  --config '{}'

Update a model

cargo-ai storage model update --uuid <model-uuid> --name "Qualified Prospects"

Remove a model

cargo-ai storage model remove <model-uuid>

Note: This will fail if the model is referenced by segments, plays, or tools. Remove or update those resources first.

Schema discovery workflow

Full flow to understand a model before querying it:

# 1. Find the model and its dataset slug
cargo-ai storage model list
cargo-ai storage dataset list

# 2. Get the full schema with column types (optional — also returns SQL dialect)
cargo-ai storage model get <model-uuid>
cargo-ai storage model get-ddl <model-uuid>

# 3. Query using <datasetSlug>.<modelSlug> as the table name
cargo-ai storage query execute \
  "SELECT uuid, name, domain FROM default.companies LIMIT 10"

Storage query examples

Run SQL against workspace storage with cargo-ai storage query execute. Tables are referenced as <datasetSlug>.<modelSlug> and rewritten to the underlying storage table under the hood. No DDL lookup is required for the table name — just use the dataset and model slugs.

For column slugs, run cargo-ai storage column list --model-uuid <uuid> or cargo-ai storage model get-ddl <model-uuid> (the DDL also shows column types and the SQL dialect).

Basic query flow

# 1. Discover the dataset slug and the model slug
cargo-ai storage dataset list   # → datasets[].slug (e.g. "default")
cargo-ai storage model list     # → models[].slug   (e.g. "companies")

# 2. Query using <datasetSlug>.<modelSlug> as the table name
cargo-ai storage query execute \
  "SELECT name, domain, employee_count FROM default.companies LIMIT 10"

Success response:

{
  "rows": [
    { "name": "Acme Corp", "domain": "acme.com", "employee_count": 500 },
    { "name": "Globex", "domain": "globex.com", "employee_count": 1200 }
  ]
}

Failed commands exit non-zero with {"errorMessage": "..."} (or {"reason": "clientNotFound"|"unknown"}). See the error handling section below.

Query with WHERE clauses

# Filter by a column
cargo-ai storage query execute \
  "SELECT name, domain FROM default.companies WHERE employee_count > 100"

# Multiple conditions
cargo-ai storage query execute \
  "SELECT name, domain, revenue FROM default.companies WHERE employee_count > 100 AND country = 'US'"

# LIKE for partial matches
cargo-ai storage query execute \
  "SELECT name, domain FROM default.companies WHERE name LIKE '%tech%'"

# NULL checks
cargo-ai storage query execute \
  "SELECT name, domain FROM default.companies WHERE email IS NOT NULL"

Aggregation queries

# Count records
cargo-ai storage query execute \
  "SELECT COUNT(*) as total FROM default.companies"

# Group by with counts
cargo-ai storage query execute \
  "SELECT country, COUNT(*) as count FROM default.companies GROUP BY country ORDER BY count DESC"

# Sum and average
cargo-ai storage query execute \
  "SELECT country, SUM(revenue) as total_revenue, AVG(employee_count) as avg_employees FROM default.companies GROUP BY country"

Pagination

Page through large result sets with SQL LIMIT and OFFSET clauses. Always include an ORDER BY so pages are stable across calls.

# First page
cargo-ai storage query execute \
  "SELECT * FROM default.companies ORDER BY name LIMIT 100 OFFSET 0"

# Second page
cargo-ai storage query execute \
  "SELECT * FROM default.companies ORDER BY name LIMIT 100 OFFSET 100"

Download full results

For exporting full result sets to a file, use storage query download. The response is a signed URL.

cargo-ai storage query download \
  --query "SELECT name, domain, employee_count, revenue FROM default.companies ORDER BY revenue DESC"

# Choose the format (csv default, parquet supported)
cargo-ai storage query download \
  --query "SELECT * FROM default.companies" --format parquet

Query across multiple models

Join on <datasetSlug>.<modelSlug> table references:

cargo-ai storage query execute \
  "SELECT c.name, c.domain, d.stage, d.amount FROM default.companies c JOIN default.deals d ON c._id = d.company_id WHERE d.amount > 10000"

Common table expressions

cargo-ai storage query execute \
  "WITH recent AS (SELECT * FROM default.companies WHERE created_at >= CURRENT_DATE - INTERVAL '30' DAY) SELECT count(*) FROM recent"

Date queries

# Records created in the last 30 days
cargo-ai storage query execute \
  "SELECT name, created_at FROM default.companies WHERE created_at >= DATE_SUB(CURRENT_DATE(), INTERVAL 30 DAY)"

# Records in a specific range
cargo-ai storage query execute \
  "SELECT name, created_at FROM default.companies WHERE created_at BETWEEN '2025-01-01' AND '2025-03-31'"

Subqueries

# Companies with above-average employee count
cargo-ai storage query execute \
  "SELECT name, employee_count FROM default.companies WHERE employee_count > (SELECT AVG(employee_count) FROM default.companies)"

Error handling

If a query fails, the command exits non-zero. Failure shapes:

{ "errorMessage": "Table not found: default.nonexistent" }

{ "reason": "clientNotFound" }

Common causes:

• Wrong dataset or model slug → re-check with storage dataset list and storage model list
• Syntax error → check SQL syntax for your storage SQL dialect (BigQuery vs Snowflake) — storage model get-ddl reports language
• clientNotFound → no storage client is configured for this workspace

Discovery commands

cargo-ai storage dataset list                  # all datasets (uuid, slug)
cargo-ai storage model list                    # all models (uuid, name, slug)
cargo-ai storage model get-ddl <model-uuid>    # column types and SQL dialect
cargo-ai storage column list --model-uuid <uuid>  # column slugs for a model

Response shapes

JSON response structures returned by Cargo CLI commands used in the cargo-storage skill.

cargo-ai storage model list

{
  "models": [
    {
      "uuid": "model-uuid",
      "workspaceUuid": "...",
      "slug": "companies",
      "name": "Companies",
      "datasetUuid": "dataset-uuid",
      "extractorSlug": "hubspot_companies",
      "idColumnSlug": "uuid",
      "titleColumnSlug": "name",
      "timeColumnSlug": null,
      "columns": [
        { "slug": "name", "type": "string", "label": "Name", "kind": "original", "originalSlug": "name" },
        { "slug": "domain", "type": "string", "label": "Domain", "kind": "original", "originalSlug": "domain" }
      ],
      "additionalColumns": [
        { "slug": "full_name", "type": "string", "label": "Full Name", "kind": "computed", "expression": { "kind": "jsExpression", "expression": "..." }, "columnsUsed": ["first_name", "last_name"] },
        { "slug": "total_deals", "type": "number", "label": "Total Deals", "kind": "metric", "relationshipUuid": "...", "aggregation": { "function": "count", "columnSlug": "uuid" } }
      ],
      "playsCount": 2,
      "segmentsCount": 1,
      "isPaused": false,
      "lastRun": {
        "uuid": "run-uuid",
        "status": "success",
        "errorMessage": null,
        "createdAt": "2025-01-15T00:00:00Z",
        "finishedAt": "2025-01-15T00:01:00Z"
      },
      "createdAt": "2025-01-01T00:00:00Z",
      "updatedAt": "2025-01-15T00:00:00Z"
    }
  ]
}

Key fields: uuid, slug, name, datasetUuid, idColumnSlug, columns (original columns), additionalColumns (custom/computed/metric/lookup columns).

Columns have no uuid — they are identified by slug within the model.

cargo-ai storage model get

Same structure as a single item from model list, nested under model:

{
  "model": {
    "uuid": "model-uuid",
    "slug": "companies",
    "name": "Companies",
    "datasetUuid": "dataset-uuid",
    "columns": [...],
    "additionalColumns": [...]
  }
}

cargo-ai storage model get-ddl

{
  "ddl": "CREATE TABLE `datasets_default.models_companies` (\n  `uuid` STRING,\n  `name` STRING,\n  `domain` STRING,\n  `employee_count` INT64,\n  `created_at` TIMESTAMP\n)",
  "language": "bigquery"
}

Key fields: ddl (contains the storage-native table name and column names), language (SQL dialect).

For cargo-ai storage query execute, reference tables as <datasetSlug>.<modelSlug> (e.g. default.companies).

cargo-ai storage dataset list

{
  "datasets": [
    {
      "uuid": "dataset-uuid",
      "slug": "default",
      "workspaceUuid": "...",
      "config": { "kind": "object" },
      "createdAt": "2025-01-01T00:00:00Z"
    }
  ]
}

cargo-ai storage dataset get

{
  "dataset": {
    "uuid": "dataset-uuid",
    "slug": "default",
    "workspaceUuid": "...",
    "config": { "kind": "object" }
  }
}

cargo-ai storage column list

Returns the model's columns (both original and additional). All columns share base fields: slug, type, label, kind. Columns have no uuid — use slug to identify them.

{
  "columns": [
    {
      "slug": "name",
      "type": "string",
      "label": "Name",
      "kind": "original",
      "originalSlug": "name"
    },
    {
      "slug": "full_name",
      "type": "string",
      "label": "Full Name",
      "kind": "computed",
      "expression": { "kind": "jsExpression", "expression": "..." },
      "columnsUsed": ["first_name", "last_name"]
    }
  ]
}

Kind-specific fields are included alongside the base fields:

`computed`

{
  "kind": "computed",
  "expression": { "kind": "jsExpression", "value": "record.first_name + \" \" + record.last_name" },
  "columnsUsed": ["first_name", "last_name"]
}

`metric`

{
  "kind": "metric",
  "relationshipUuid": "relationship-uuid",
  "aggregation": {
    "function": "count",
    "columnSlug": "uuid"
  },
  "filter": null
}

`lookup`

{
  "kind": "lookup",
  "join": {
    "toModelUuid": "company-model-uuid",
    "fromColumnSlug": "company_uuid",
    "toColumnSlug": "uuid"
  },
  "extractColumnSlug": "name",
  "filter": null
}

cargo-ai storage relationship list

{
  "relationships": [
    {
      "uuid": "relationship-uuid",
      "fromModelUuid": "contacts-model-uuid",
      "toModelUuid": "companies-model-uuid",
      "fromColumnSlug": "company_uuid",
      "toColumnSlug": "uuid",
      "relation": "manyToOne"
    }
  ]
}

cargo-ai storage record list

{
  "records": [
    {
      "uuid": "record-uuid",
      "name": "Acme Corp",
      "domain": "acme.com",
      "employee_count": 500
    }
  ]
}

cargo-ai storage query execute

Tables are referenced as <datasetSlug>.<modelSlug> and rewritten to the underlying storage table under the hood.

Success:

{
  "rows": [
    { "name": "Acme Corp", "domain": "acme.com", "employee_count": 500 },
    { "name": "Globex", "domain": "globex.com", "employee_count": 1200 }
  ]
}

Failure (non-zero exit):

{ "errorMessage": "Table not found: default.nonexistent" }

{ "reason": "clientNotFound" }

{ "reason": "unknown" }

cargo-ai storage query download

Used for full exports. Same table-naming convention as storage query execute (<datasetSlug>.<modelSlug>). Pass the SQL via --query; the response is a signed URL.

Success:

{
  "url": "https://signed-url-to-csv-or-parquet-file"
}

Failure (non-zero exit):

{ "errorMessage": "Table not found: default.nonexistent" }

Troubleshooting

Common errors and recovery steps for cargo-storage commands.

General

Models

Columns

Relationships

Records

Queries (storage query execute / storage query download)