​
kvcdn upload

Upload a local .kv artifact to the hosted service.

​
Usage

kvcdn upload <FILE> [OPTIONS]

​
Arguments

ArgumentDescription
FILELocal path to the .kv artifact

​
Options

OptionDefaultDescription
--nameinferred from filenameHuman-readable artifact name
--visibilityprivateprivate or public
--api-urlfrom KVCDN_API_URLBase URL of the hosted portal API
--api-keyfrom KVCDN_API_KEYAPI key for authentication

​
Example

export KVCDN_API_URL=https://api.kvcachestore.com
export KVCDN_API_KEY="kv_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

kvcdn upload ./context.kv --name "Qwen system prompt" --visibility private

​
How it works

  1. The CLI reads the artifact’s JSON sidecar for model_name, dtype, and num_tokens.
  2. The CLI creates artifact metadata in the portal (POST /api/v1/artifacts/upload-url).
  3. The portal returns a presigned URL for direct upload to object storage.
  4. The CLI PUTs the file to the presigned URL and then calls POST /api/v1/artifacts/{id}/confirm-upload.
The artifact then appears in the dashboard at https://kvcachestore.com/app.

​
Public URL

For public artifacts, the dashboard and API expose a CDN URL: 
https://x.kvcdn.io/{org_slug}/{project_slug}/{artifact_id}
This URL is immutable and can be fetched anonymously. Consumers download the .kv file and load its tensors into the matching model to skip context prefill.

​
Notes

  • Free accounts are limited to 20 artifacts. Upgrade in the dashboard to raise the limit.
  • Presigned URLs expire after 15 minutes. If an upload fails, retry kvcdn upload to request a fresh URL.
  • Public artifacts can be downloaded by anyone; private artifacts are restricted to your account.
  • The CLI is an x86-64 Linux binary. ARM64 support is planned for a future release.

​
See also