# Configure the CLI
> ~/.vcuprc JSON schema, VCUP_API_URL and VCUP_TOKEN precedence, and matching client settings to a deployed instance.
- Repository: MaxLeiter/vcup
- GitHub: https://github.com/MaxLeiter/vcup
- Human docs: https://grok-wiki.com/public/docs/maxleiter-vcup-05c16ae77ebb
- Complete Markdown: https://grok-wiki.com/public/docs/maxleiter-vcup-05c16ae77ebb/llms-full.txt
## Source Files
- `cli.ts`
- `README.md`
- `package.json`
---
---
title: "Configure the CLI"
description: "~/.vcuprc JSON schema, VCUP_API_URL and VCUP_TOKEN precedence, and matching client settings to a deployed instance."
---
The `vcup` binary resolves API base URL and bearer token once per invocation via `loadConfig()` in `cli.ts`: it reads `VCUP_API_URL` and `VCUP_TOKEN`, optionally merges them with `~/.vcuprc`, and uses the result for `POST ${url}/api/upload` and `DELETE ${url}/api/delete`.
## Configuration surface
| Surface | Path or name | Used for |
| --- | --- | --- |
| Config file | `~/.vcuprc` | Default `url` and `token` when env vars are absent or partial |
| Client env | `VCUP_API_URL` | API deployment origin (overrides or replaces `url` in rc) |
| Client env | `VCUP_TOKEN` | Shared secret sent as `Authorization: Bearer` (overrides or replaces `token` in rc) |
| Client env (delete only) | `BLOB_STORE_URL` | Resolving proxy `/f/…` URLs to raw blob URLs for `vcup rm` |
Server-side variables (`VCUP_TOKEN` on Vercel, `VCUP_BASE_URL`, blob store settings) are not read by `loadConfig()`; they must match what you deploy. See [Deploy on Vercel](/deploy-vercel) and [Environment variables](/environment-variables).
## `~/.vcuprc` schema
The CLI expects a single JSON object with two string fields. There is no schema validator beyond `JSON.parse` and property access.
Deployment origin for API calls. Becomes the prefix in `${url}/api/upload` and `${url}/api/delete`. Use the Vercel deployment URL or your custom domain root (no path suffix).
Must equal the `VCUP_TOKEN` value configured on the server. Sent on every authenticated API request.
```json title="~/.vcuprc"
{
"url": "https://your-vcup-deployment.vercel.app",
"token": "your-vcup-token"
}
```
Invalid JSON in `~/.vcuprc` throws at parse time and aborts the process. Missing `url` or `token` after merging env and file yields requests with `undefined` in the URL or header—configure both values explicitly.
## Resolution order
`loadConfig()` applies a two-stage rule set:
1. **Full env shortcut** — If both `VCUP_API_URL` and `VCUP_TOKEN` are set, return them immediately. `~/.vcuprc` is not read.
2. **File with per-field env override** — If `~/.vcuprc` exists, parse it and set `url` to `process.env.VCUP_API_URL || rc.url` and `token` to `process.env.VCUP_TOKEN || rc.token`.
3. **Failure** — If neither step yields a usable pair and the file is missing, print a sample config to stderr and exit with code `1`.
```text
┌─────────────────────────┐
│ VCUP_API_URL set? │
│ AND VCUP_TOKEN set? │
└───────────┬─────────────┘
yes │ no
┌───────────▼───────────┐ ┌──────────────────────┐
│ return env only │ │ ~/.vcuprc exists? │
│ (skip rc file) │ └──────────┬───────────┘
└───────────────────────┘ yes │ no
┌───────────▼──────────┐
│ url = env || rc.url │
│ token= env || rc.token│
└───────────┬──────────┘
missing file
┌───────────▼──────────┐
│ stderr + exit(1) │
└──────────────────────┘
```
| `VCUP_API_URL` | `VCUP_TOKEN` | `~/.vcuprc` | Result |
| --- | --- | --- | --- |
| set | set | any | Env only; rc ignored |
| set | unset | present | `url` from env, `token` from rc |
| unset | set | present | `url` from rc, `token` from env |
| unset | unset | present | Both from rc |
| partial or none | partial or none | absent | Exit `1` with sample JSON |
Setting only one env var without a rc file fails at step 3. Use a rc file for split storage (e.g. token in env, URL on disk) or export both env vars.
## Match client settings to a deployment
After [Deploy on Vercel](/deploy-vercel), align three values:
| Client field | Server source | Must match |
| --- | --- | --- |
| `url` / `VCUP_API_URL` | Deployment hostname | Origin that serves `/api/upload` and `/api/delete` on your project |
| `token` / `VCUP_TOKEN` | Project env `VCUP_TOKEN` | Exact string; upload and delete handlers compare `Authorization: Bearer` to `process.env.VCUP_TOKEN` |
Use the Vercel project URL (e.g. `https://your-project.vercel.app`) as `url`. For a custom domain, use that host instead—see [Custom domain](/custom-domain).
Set the same secret in Vercel **Environment Variables** as `VCUP_TOKEN` and in `~/.vcuprc` as `token` (or export `VCUP_TOKEN` locally).
Create `~/.vcuprc` or export env vars. Prefer env in CI; prefer rc on a developer machine.
Run `vcup --help` (no config required), then upload a small file. A `401` means token mismatch; connection errors often mean wrong `url`.
### URL shape
The CLI concatenates paths as `config.url` + `/api/upload` (and `/api/delete`). Use a base origin without a trailing slash, e.g. `https://my-vcup.vercel.app`, not `https://my-vcup.vercel.app/`.
### Proxy URLs vs API URL
`url` targets the **API**, not the blob CDN. Upload responses include a proxy link `${baseUrl}/f/${slug}` where `baseUrl` on the server is `VCUP_BASE_URL` or inferred from request headers—not from your rc `url`. If printed links should use a custom public host, set server `VCUP_BASE_URL`; your rc `url` can still point at the default deployment for API calls. Details: [Proxy and raw URLs](/proxy-and-raw-urls), [Custom domain](/custom-domain).
### Optional `BLOB_STORE_URL` on the client
Not part of `loadConfig()`. Required only when running `vcup rm` with a proxy URL containing `/f/`; the CLI maps the slug to `${BLOB_STORE_URL}/${slug}` before calling delete. Use the raw blob URL from upload `--raw` to avoid setting it. See [Upload and delete](/upload-and-delete).
## Environment vs file
```json title="Persistent local config"
{
"url": "https://your-vcup-deployment.vercel.app",
"token": "your-vcup-token"
}
```
```bash title="Shell or CI"
export VCUP_API_URL="https://your-vcup-deployment.vercel.app"
export VCUP_TOKEN="your-vcup-token"
```
Help text documents the same contract: `vcup --help` lists the rc shape and names `VCUP_API_URL` / `VCUP_TOKEN`.
## What config does not control
| Concern | Where it lives |
| --- | --- |
| Blob read/write credentials | Server `BLOB_READ_WRITE_TOKEN` |
| Proxy fetch target store | Server `BLOB_STORE_URL` |
| Public link host in upload JSON | Server `VCUP_BASE_URL` (optional) |
| Inline file serving at `/f/:slug` | Public; no client token |
## Errors and checks
| Symptom | Likely cause |
| --- | --- |
| `Missing config. Set VCUP_API_URL…` | No rc file and incomplete env pair |
| `Upload failed: 401` | Client `token` ≠ server `VCUP_TOKEN` |
| `Upload failed: 400` | Missing `X-Filename` (CLI always sets it for uploads) |
| Wrong host in printed share link | Server `VCUP_BASE_URL` / forward headers, not rc `url` |
| `Cannot resolve proxy URL without BLOB_STORE_URL` | `vcup rm` on proxy URL without client `BLOB_STORE_URL` |
For local API testing with `vercel dev`, point `url` at the dev server origin and use the same `VCUP_TOKEN` as in your local `.env`. See [Local development](/local-development).
## Related pages
Configure, upload one file, and open the proxy URL.
How `VCUP_TOKEN` is checked on upload and delete.
Server env vars to copy into client config.
Full client and server key listing.
Client vs server variable matrix.
Config-related failure modes and HTTP statuses.