Quickstart

Five minutes from here you’ll have a bucket, an object in it, and a shareable URL to download that object.

This page uses the dodil k3 CLI for the shortest path to a working object. The same operations are available over raw HTTP (bearer token + JSON) and any S3-compatible SDK (aws s3, boto3, @aws-sdk/client-s3, …).

Prerequisites

You need three things:

1. The dodil CLI installed locally — see CLI Basics.
2. Dodil service-account credentials (<service_account_id>, <service_account_secret>) for your organization.
3. Network access to a K3 gateway:
   • Staging: https://k3.dev.dodil.io (HTTP) · k3-grpc.dev.dodil.io:443 (gRPC)
   • Production: https://k3.dodil.io (HTTP) · k3-grpc.dodil.io:443 (gRPC)

Sign in once — this writes ~/.config/dodil/config.yaml so every subsequent dodil k3 command resolves endpoint, token, and org automatically:

dodil auth login

Opens a browser; for non-interactive / CI, set DODIL_SERVICE_ACCOUNT_ID + DODIL_SERVICE_ACCOUNT_SECRET and run the same command.

1. Verify the connection

dodil k3 bucket list

Empty result is fine — it confirms auth, org context, and gateway reachability. If this fails, fix it before continuing (most failures are token-expired or wrong org).

2. Create a bucket

dodil k3 bucket create kb-quickstart -d "My first K3 bucket"

A bucket name is unique within your org. Defaults: access_mode = PRIVATE, no quota. See Buckets — API Reference for the full shape.

3. Upload your first object

echo "hello, k3" > hello.txt
dodil k3 object create ./hello.txt -b kb-quickstart -k greetings/hello.txt

object create uploads via HTTP PUT under the hood — the gRPC service has no byte plane. See Objects — byte plane for why.

4. List and inspect

# What's in the bucket
dodil k3 object list -b kb-quickstart
 
# Metadata for a specific key (size, etag, content-type, per-pipeline index status)
dodil k3 object show greetings/hello.txt -b kb-quickstart -o json

ObjectInfo returned here is the same type documented in Core Concepts → Object.

5. Share it — presigned URL

URL=$(dodil k3 object url greetings/hello.txt -b kb-quickstart --expires 3600)
echo "$URL"
curl -s "$URL"

The URL is signed with a K3 token good for 1 hour (default; max 24 h). Anyone with the link can GET the object — no auth headers needed. Mirror of GetObjectUrl.

What you just did

Every successful upload also enters K3’s pipeline plane — if your bucket has matching ingest rules, the object is automatically discovered and routed to a vector index or warehouse. See Pipelines when you’re ready to wire that up.

Cleanup

dodil k3 object remove greetings/hello.txt -b kb-quickstart
dodil k3 bucket delete kb-quickstart

A bucket must be empty before it can be deleted — DeleteBucket returns an error otherwise.

Next steps

• S3 Compatibility — use aws s3, boto3, or @aws-sdk/client-s3 against the K3 gateway.
• Recipes — direct-from-browser upload, multipart for large files, static-site hosting.
• Core Concepts — Bucket, ObjectInfo, BucketPolicy, BucketCorsConfiguration, PresignedURL.
• API Reference — full gRPC + HTTP contracts per resource.
• CLI Guide — every dodil k3 ... command in detail.