# Installation
> Install the global @maxleiter/vcup CLI with bun or npm, prerequisites, and how the published bin maps to cli.ts.
- 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
- `package.json`
- `README.md`
- `cli.ts`
---
---
title: "Installation"
description: "Install the global @maxleiter/vcup CLI with bun or npm, prerequisites, and how the published bin maps to cli.ts."
---
The npm package `@maxleiter/vcup` (version `0.1.0`) publishes a single global command, `vcup`, whose `package.json` `bin` entry points at `cli.ts`. That file is executed by Bun via `#!/usr/bin/env bun`; the CLI talks to a separately deployed Vercel API (`POST /api/upload`, `DELETE /api/delete`) and does not start the server or Blob store on install.
## Prerequisites
| Requirement | Why it matters |
| --- | --- |
| **Bun on `PATH`** | `cli.ts` starts with `#!/usr/bin/env bun`; the global shim invokes that interpreter. |
| **A deployed vcup API** | Upload and delete call `config.url` (from `~/.vcuprc` or `VCUP_API_URL`). Install only adds the client; deploy your own instance or use an existing deployment. |
| **Matching `VCUP_TOKEN`** | Server handlers compare `Authorization: Bearer …` to `process.env.VCUP_TOKEN`; the client must use the same secret after configuration. |
Global install does not create `~/.vcuprc`, set environment variables, or provision Vercel Blob. Those steps come after install; see [Configure the CLI](/configure-cli) and [Deploy on Vercel](/deploy-vercel).
## Install the CLI globally
```bash
bun install -g @maxleiter/vcup
```
```bash
npm install -g @maxleiter/vcup
```
Both commands install the scoped package from the registry and place a `vcup` executable on your global binary path. The repository documents these two installers in its README; there is no separate CLI-only package name.
## How `bin` maps to `cli.ts`
`package.json` declares the executable mapping:
```json
"bin": {
"vcup": "./cli.ts"
}
```
After a global install, package managers link `vcup` to the published `cli.ts` in the package root. Invoking `vcup` runs that file; the shebang delegates execution to Bun:
```text
@maxleiter/vcup (npm package)
├── package.json → "bin": { "vcup": "./cli.ts" }
├── cli.ts → #!/usr/bin/env bun (upload / rm / --help)
└── api/ → Vercel serverless handlers (not started by the bin)
```
The same tarball contains `api/upload.ts`, `api/delete.ts`, and `api/f.ts` plus server dependencies (`@vercel/blob`, `mime-types`). Those are used when the repo is deployed to Vercel, not when you run the global `vcup` command. The CLI uses Node/Bun built-ins (`fs`, `path`, `os`) and `fetch` only.
## What gets installed
| Artifact | Role |
| --- | --- |
| `vcup` on `PATH` | Global command linked to `cli.ts` |
| `cli.ts` | Client: upload streaming, `vcup rm`, `--raw`, `--help` |
| `api/*.ts` | Server routes; inactive until deployed with `vercel dev` or Vercel |
| Dependencies | `@vercel/blob`, `mime-types` — required by API handlers, not imported by `cli.ts` |
Package metadata at publish time: name `@maxleiter/vcup`, version `0.1.0`, description *Simple file sharing via Vercel Blob*. The only `scripts` entry in `package.json` is `"dev": "vercel dev"` for local server work, not for end-user CLI setup.
## Verify the installation
```bash
which vcup
vcup --help
```
`--help` (or no args with a TTY and no stdin) prints usage and exits before `loadConfig()` runs, so a fresh install can be checked without `~/.vcuprc` or env vars.
Upload and delete require `VCUP_API_URL` + `VCUP_TOKEN`, or a `~/.vcuprc` with `url` and `token`. Without them, the CLI prints a sample JSON config and exits with code `1`.
```bash
$ vcup --help
vcup — simple file sharing via Vercel Blob
Usage:
vcup Upload a file
echo "hi" | vcup Upload from stdin
vcup rm Delete a file by its proxy or raw URL
vcup --raw Print raw blob URL instead of proxy URL
vcup --help Show this help
```
## Install vs deploy
```mermaid
flowchart LR
subgraph client["Your machine"]
CLI["vcup\n(cli.ts via Bun)"]
end
subgraph npm_pkg["@maxleiter/vcup package"]
BIN["bin → cli.ts"]
API["api/* handlers"]
end
subgraph vercel["Vercel deployment"]
UP["POST /api/upload"]
DEL["DELETE /api/delete"]
PROXY["GET /f/:slug → api/f"]
BLOB["Vercel Blob store"]
end
BIN --> CLI
CLI -->|Bearer + X-Filename| UP
CLI -->|Bearer + X-Blob-Url| DEL
API --> UP
API --> DEL
API --> PROXY
UP --> BLOB
PROXY --> BLOB
```
- **Global install** — client only (`vcup`).
- **Vercel deploy** — clone/deploy the repo (or your fork), set `BLOB_READ_WRITE_TOKEN`, `BLOB_STORE_URL`, and `VCUP_TOKEN` per `.env.example`, then point the CLI at that deployment’s base URL.
If `vcup` fails with “env: bun: No such file or directory” (or similar), install Bun and ensure `bun` is on `PATH`. The published bin does not bundle a Node-compatible prebuilt JavaScript entry.
## Optional: run from a git checkout
Contributors can use the repo directly instead of a global registry install: clone the repository, install dependencies with Bun, and run `bun cli.ts` or link locally. Production CLI usage documented in the README is `bun install -g` / `npm install -g @maxleiter/vcup`. Local server iteration uses `npm run dev` (`vercel dev`); see [Local development](/local-development).
## Related pages
Configure `~/.vcuprc`, upload one file, and confirm the proxy URL.
`~/.vcuprc` schema and env precedence for `url` / `token`.
Blob store, env vars, and post-deploy steps for the API your CLI calls.
End-to-end surfaces: CLI, proxy URLs, and runtime assumptions.