---
name: vibiz-files
description: Store and find files in a Vibiz Stack project's Files (a drive per project with permanent links) - find an image, video or audio you or the app generated earlier, upload a logo or product photo and get its link, import a file from a URL, private files with signed links, and file uploads from the app with one key. Use when you need a file's permanent URL, want to reuse something generated before, or an app needs to store user uploads, avatars or downloads.
---

# Vibiz files

**Connect first.** Not logged in (a tool answers `unauthorized` with `reason: not_logged_in`, or the CLI says "Not logged in")? Run `npx @vibiz/cli login`: show the person the link it prints and ask them to click Authorize (their account is opened on the way if they have none), then go on. Or connect the remote MCP server, nothing to install: `claude mcp add --transport http vibiz https://app.vibiz.app/mcp` (the client opens the same sign-in on first use). Never ask the person to paste a key into the chat. **Keep the CLI current:** a command named here that your `vibiz` doesn't have (an unknown-command or usage error) means the CLI is out of date, not that Vibiz can't do it: run `npm install -g @vibiz/cli@latest` (or `npx -y @vibiz/cli@latest <command>`) and retry, and refresh these skills with `vibiz skills add --global`. Never tell the person something isn't possible because an old CLI lacks the command.

Every project has **Files**, with nothing to turn on (no resource, no hosting). Every image, video and audio generated for the project (with `project_id`, `--project`, or the project's app or AI key) is saved there by itself, with its model, prompt and cost. Use the `url` in the response: it is permanent. Uploads from the app, the CLI or you sit next to them.

## Find a file

- Newest: `vibiz_files { project_id, action: "latest", type?: "image" }` (or `vibiz files latest --type image`).
- Search: `vibiz_files { project_id, action: "list", q: "<words from the prompt or name>" }` (or `vibiz files search "<words>"`). Filters: `type` (image, video, audio, other), `source` (upload, ai), `model`, `tag`, `folder`, `since`/`until` (ISO, or `30m`, `4h`, `2d`, `1w`), `limit` (≤100), `cursor`.
- One file in full: `action: "get", file_id`. Look before generating again: reusing a file is free.

## Add a file

- From a public URL: `vibiz_files { project_id, action: "import", url, name?, folder? }` (at most 50 MB).
- From this machine: `vibiz files upload logo.png hero.jpg [--folder brand] [--private]` prints each permanent link.
- From the app's server, with its one key (`VIBIZ_APP_KEY`, `@vibiz/app`):

  ```ts
  import { vibiz } from '@vibiz/app';
  const avatar = await vibiz.files.upload(bytes, { name: 'avatar.png', contentType: 'image/png' });
  await db.users.update(userId, { avatarUrl: avatar.url });
  ```

  Also `vibiz.files.list()`, `latest()`, `get(id)`, `delete(id)`, always in the key's own project and environment. Without the package: `POST /v1/app/files` with the bytes as the body and `?name=`.

## Facts

- Links: `https://app.vibiz.app/f/<random key>/<name>`, public on purpose (an `<img>`, an email or a social platform can't send a key) and unguessable. A **private** file (`private: true` / `--private`) gets a signed link valid one hour: fetch the file again for a fresh one.
- 50 MB a file. HTML, JavaScript and XML are refused (`invalid_request`, `param: "content-type"`): they would run as a page.
- Production and development are separate drives; development keys save to development. `env: "development"` (`--dev`) reads it.
- Without a project, generated media is not saved and its links last 24 hours.
- Storage is free during the beta (the bytes kept are recorded as `files.storage` in usage).

## Never

- Deleting (`action: "delete"`, `vibiz files rm <id>`) breaks the link everywhere it is used (pages, emails, posts): only when the person asks.
- Don't upload secrets or `.env` files; files are content, readable by anyone with the link unless private.

**Console links**: `/projects/<id>/files` (`?type=image&source=ai`, `env`, `file=<id>`); list results carry `console_url`: give the person that link.

## References

- `references/files.md`: the file object, routes, limits.
- `references/app-sdk.md`: every `@vibiz/app` call.