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 $K3_TOKEN" \
  -H "x-organization-id: $K3_ORG" \
  -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 $K3_TOKEN" \
  -H "x-organization-id: $K3_ORG" \
  -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 CLI index