CLI Basics

K3 runs as a plugin under Dodil CLI:

dodil k3 <command> [subcommand] [flags]

Install and authenticate the dodil CLI once — dodil 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.

Config

K3 reads the shared dodil config (see Install the CLI ). Its product-specific bits: the endpoint environment variable is K3_API_ENDPOINT, and config keys live under k3.* (with a global.* fallback). DODIL_TOKEN and DODIL_ORG apply across products.

Global Flags

Output Modes

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

Example:

dodil k3 bucket list -o json

Command Discovery

dodil k3 --help
dodil k3 <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. Bucket policy and bucket CORS command coverage is missing.
2. Source lifecycle coverage is partial (CLI has source create, API has full CRUD).
3. External vector write APIs are not first-class CLI commands:
   • InsertVectors
   • UpsertVectors
   • DeleteVectors
4. Table pipeline creation is API-only (CreateTablePipeline).
5. Pagination/filter controls available in API are only partially surfaced in CLI flags.

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 use API for the uncovered feature in the same workflow.

Example: table pipeline creation (API fallback)

curl -sS -X POST "https://k3.dev.dodil.io/<bucket>/tables/pipelines" \
  -H "Authorization: Bearer $DODIL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "bucket": "<bucket>",
    "name": "leases",
    "template_id": "lease_extraction"
  }'

Example: external vector upsert (API fallback)

curl -sS -X PUT "https://k3.dev.dodil.io/<bucket>/vector/collections/<collection_id>/vectors" \
  -H "Authorization: Bearer $DODIL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "bucket": "<bucket>",
    "collection_id": "<collection_id>",
    "vectors": [{"id":"doc-1","dense_float":{"values":[0.1,0.2,0.3]}}]
  }'

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