Quickstart

Five minutes, three paths. Pick the one that matches how you work; the account setup in step 1 is shared by all of them.

1. Create an account, an organization and a repository

Sign up at cavsnode.com. Sign-in is handled by Firebase Authentication (email/password or a social provider).
Create an organization. Its slug is the first half of every repository reference — acme-ai/vision-models.
Create a repository. Leave the defaults (PRIVATE visibility, managed storage) unless you already know you want Bring Your Own S3.
Create an API token: Organization settings → Tokens → New token. Choose the repo:write scope for a token that can push and pull. The secret is shown exactly once — copy it now.

2. Move some bytes

The Git-native path: keep using git, and let CAVS handle the large files.

Install the CLI.
Terminal window
```
curl -fsSL https://raw.githubusercontent.com/orelvis15/cavs-hub-cli/main/install.sh | sh
```
Also install git-lfs (brew install git-lfs, apt install git-lfs) and the cavs-lfs-agent binary from the engine releases if you want chunk-level dedup. See CLI installation for per-platform detail.
Sign in. The CLI already defaults to https://cavsnode.com; only a self-hosted deployment needs cav config set api <url> first.
Terminal window
```
cav login
```
cav login prompts for the token (so it stays out of your shell history), validates it against the API and prints the organizations you can see.
Non-interactive alternative
```
echo "$CAVS_TOKEN" | cav login --token-stdin
```
Connect your Git repository. Run this inside an existing Git working tree:
Terminal window
```
cav repo connect acme-ai/vision-models
```
One command does four things: sets lfs.url to the repository’s endpoint, wires up the CAVS transfer agent, installs the pre-push hook, and uploads the initial Git index so the dashboard can show your files and history.

Track your large files and push.

git lfs track "*.safetensors"
git add .gitattributes model.safetensors
git commit -m "Add trained model"
git push

Check your work.
Terminal window
```
cav doctor          # environment + connectivity diagnosis
cav storage         # organization storage usage
```
Then open the repository in the dashboard. The Storage tab shows logical vs physical bytes and the dedup ratio; Benchmarks shows the real bytes this push moved.

Change a few megabytes inside that file, commit and push again — the second push transfers a fraction of the first.

The pipeline path: no Git, just artifacts in and out.

Install.
Terminal window
```
pip install cavs
```

Configure.

export CAVS_TOKEN=cavs_pat_...
export CAVS_API=https://cavsnode.com

Upload.

from cavs import CAVS, sha256_file

client = CAVS.from_env()

result = client.artifacts.upload(
    path="./checkpoints/resnet50.safetensors",
    project="vision-models",         # the repository slug
    name="resnet50",
    kind="model",
    version="1.4.0",
    metadata={"framework": "pytorch", "accuracy": 0.942},
)

print(result.reference)   # cavs://acme-ai/vision-models/model/resnet50:1.4.0

# Record the oid — that's what downstream consumers pin.
oid = sha256_file("./checkpoints/resnet50.safetensors")
print(oid)

Download, verified.
```
client.artifacts.download(oid, dest="./restored/model.safetensors",
                          project="vision-models")
```
Every downloaded file is hashed as it streams. A file whose SHA-256 doesn’t equal its oid raises ChecksumError and is never written to its final path.

Full guide: Python SDK.

The no-dependencies path — useful for scripting and for understanding what the SDKs do.

Set up your environment. Grab the repository UUID from the dashboard URL or from GET /organizations/{org}/repositories.

export CAVS_API=https://cavsnode.com/api/v1
export CAVS_TOKEN=cavs_pat_...
export REPO=<repository-uuid>
export FILE=./model.safetensors

Hash the file. The oid is the SHA-256.

OID=$(shasum -a 256 "$FILE" | cut -d' ' -f1)   # sha256sum on Linux
SIZE=$(wc -c < "$FILE" | tr -d ' ')

Open an upload session.

SESSION=$(curl -sS -X POST "$CAVS_API/repositories/$REPO/uploads" \
  -H "Authorization: Bearer $CAVS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: quickstart-$OID" \
  -d '{"expected_objects": 1}' | jq -r .session.id)

Ask for a presigned URL, then upload the bytes directly.

URL=$(curl -sS -X POST "$CAVS_API/repositories/$REPO/uploads/$SESSION/objects" \
  -H "Authorization: Bearer $CAVS_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"objects\":[{\"oid\":\"$OID\",\"size\":$SIZE}]}" \
  | jq -r '.objects[0].upload_url')

curl -sS -X PUT "$URL" --upload-file "$FILE"

Complete and finalize.

curl -sS -X POST "$CAVS_API/repositories/$REPO/uploads/$SESSION/objects/$OID/complete" \
  -H "Authorization: Bearer $CAVS_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"size\": $SIZE}"

curl -sS -X POST "$CAVS_API/repositories/$REPO/uploads/$SESSION/finalize" \
  -H "Authorization: Bearer $CAVS_TOKEN"

Download it back.

DL=$(curl -sS -X POST "$CAVS_API/repositories/$REPO/downloads/authorize" \
  -H "Authorization: Bearer $CAVS_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"oids\":[\"$OID\"]}" | jq -r '.objects[0].download_url')

curl -sS -o restored.bin "$DL"
shasum -a 256 restored.bin   # must equal $OID

Full guide: Plain HTTP.

3. Verify it worked

Whichever path you took:

cav whoami                  # identity + organizations
cav storage                 # organization storage usage
cav artifacts               # recent artifacts across repositories

curl -sS https://cavsnode.com/api/v1/repositories/$REPO/usage \
  -H "Authorization: Bearer $CAVS_TOKEN" | jq

In the dashboard, the repository’s Overview shows the object count and the current generation; Files shows the indexed tree; Storage shows the dedup ratio; Activity shows the push event.

Troubleshooting the first five minutes

Symptom	Cause and fix
`401 unauthorized`	Missing, mistyped or revoked token. Check `cav status`; recreate the token if unsure.
`403 forbidden`	The token’s scope or your role doesn’t grant the operation. A push needs `repo:write`. See Roles & permissions.
`402 quota_exceeded`	A plan limit was hit — storage, object size, repositories, members or tokens. The `details` object names which. See Plans & quotas.
`cav: command not found`	The installer put the binary in `~/.local/bin`; add it to `PATH`.
CLI talks to `localhost:8080`	CLI 0.1.0’s default, or a stale `api_base` in the stored config. Run `cav config set api https://cavsnode.com` (or export `CAVS_API`).
Dashboard shows no files	The Git index hasn’t been uploaded. Run `cav repo index --full`.
Push isn’t deduplicating	`cavs-lfs-agent` isn’t installed or isn’t wired. Run `cav doctor`, then CAVS LFS agent.