CLI Basics

K3 runs as a plugin under Dodil CLI:

dodil data <command> [subcommand] [flags]

Install and authenticate the dodil CLI once — dodil auth login, the shared config file, and the value-resolution order are covered in Install the CLI  (macOS, Linux, Windows). After login, K3 commands read your token, org, and endpoint from config, so you usually don’t pass them per command.

API keys

For CI and headless clients, issue a long-lived dk_… Dodil API key instead of reusing your interactive session:

dodil auth apikey issue --name ci --role k3.editor      # secret shown once
dodil auth apikey issue --name uploader --role k3.editor \
  --drn "drn:dodil:k3:<region>:<org>:bucket/<name>"     # scope to one bucket
dodil auth apikey list
dodil auth apikey rotate <lookup>                       # new secret, same lookup
dodil auth apikey revoke <lookup>                       # propagates within ~30s

The <region> in a DRN is the IAM resource region (us-east-1 in current output), not a data-plane door region — the wire adapters live in uk-lon-1, but the DRN that scopes a key uses the IAM region.

Use the key as Authorization: Bearer dk_…, or as the password in Basic auth (username ignored). Note that dodil auth login does not accept dk_ keys — they authenticate API requests, not the CLI session. For S3 SDK setup with a key, see Storage → S3 Compatibility.

Config

K3 reads the shared dodil config (see Install the CLI ). It resolves the control-plane gRPC endpoint in this order: the --api-endpoint flag → the data.api_endpoint config key → a value derived from the unified global.api_endpoint written by dodil auth login (rpc.dodil.io → rpc.data.dodil.io) → the built-in default rpc.data.dodil.io:443. A legacy k3.api_endpoint key is deliberately ignored (older configs pinned it to a host that no longer resolves). The data-plane (tables-gateway) endpoint resolves separately — --data-endpoint flag → data.data_endpoint config → derived table-rpc.<region>.dodil.io:443.

Global Flags

Output Modes

• Default: table-like output
• JSON: -o json

Example:

dodil data bucket list -o json

Command Discovery

dodil data --help
dodil data <group> --help

Next: Storage CLI — bucket & object commands

CLI Gaps and API Fallbacks

K3 CLI covers common operations well, but it does not expose the full API surface yet.

High-Impact Gaps

1. Source lifecycle is partial — dodil data source has create, list, and get, but no update or delete; edit or remove a source through the API.
2. Vector writes are a data-plane operation, not a control-plane CLI command. The plane’s write RPCs are UpsertVectors / DeleteVectors on TablesVector (there is no InsertVectors). Write vectors over the Qdrant/Pinecone wire adapters or by inserting into a VECTOR(n) table with SQL; dodil data vsearch is the read (KNN) side.
3. Pagination/filter controls available in the API are only partially surfaced in CLI flags.

Already covered — no longer gaps. Bucket policy and CORS (dodil data bucket policy / dodil data bucket cors, each with set/get/delete) and table-pipeline creation (dodil data table pipeline create) all ship in the CLI today.

Naming/Compatibility Gotchas

1. ingest add --collection maps to API pipeline_id.
2. Search may route through compatibility mapping in some adapter paths.
3. object create can fail if --api-endpoint lacks https://.

Recommended Fallback Pattern

Use CLI for daily operations and reach for another surface only for the uncovered feature in the same workflow.

Table pipeline creation is now a CLI command — no API fallback needed:

dodil data table pipeline create leases -b "$BUCKET" --template lease_extraction

Vector writes are a data-plane operation. The control plane does not accept vector writes (the old /:bucket/vector/... route tree was removed). Upsert vectors over a stock Qdrant or Pinecone client, or INSERT into a VECTOR(n) column over the Postgres wire — see Connect & Adapters for the endpoints and credentials. The plane RPCs behind those wires are UpsertVectors / DeleteVectors on TablesVector.

Quick Decision Guide

Use CLI when:

• there is a direct command with required flags
• you need quick operator workflows
• human-readable output is enough

Use API when:

• command does not exist in CLI
• you need detailed pagination/filtering
• you need precise request body control

Back to Overview

See also

• Object Storage · Pipelines · Tables · Vector
• Auth and Access
• Operations · Feature Status