> ## Documentation Index
> Fetch the complete documentation index at: https://vetta.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# vetta app

> Create and deploy a hosted app by hand, read the ones a project declaration provisioned, and poll the build that finishes after the apply returns.

An app is provisioned by a project's declaration, not by a verb: `naive up` creates it, writes its
secrets, connects its domains and ships its `deploy_dir`. See [`naive`](/docs/cli/naive).

Two commands write: `create` makes an app that has no declaration — the quickest way to a
[database](/docs/cli/database) is `vetta app create <name> --type fullstack` — and `deploy` ships a
directory to it. Secrets, domains, updates and deletion stay with the declaration, which owns every
app it names; an app made here can be adopted by one later with `naive up --adopt`.

The rest read. What a declaration cannot do for you is *wait*: an app's asynchronous halves advance
on read, so `naive up` returns as soon as the deployment is accepted and the build is still running.
These commands are the poll.

Reads require the `agents:read` scope; `create` and `deploy` require `agents:write`.

## Commands

| Command                                 | Description                                                    |
| --------------------------------------- | -------------------------------------------------------------- |
| `vetta app create <name> --type <type>` | Make an app: `fullstack` (with a database) or `frontend_only`. |
| `vetta app deploy <app-id> <dir>`       | Ship a directory as one deployment.                            |
| `vetta app list`                        | Every app in the organization, or the one with a given name.   |
| `vetta app show <app-id>`               | One app: its type, its URL, its project stamp.                 |
| `vetta app deployments <app-id>`        | The build history, newest first.                               |
| `vetta app secrets <app-id>`            | The app's secret **names** and value hashes — never a value.   |
| `vetta app domains <app-id>`            | The custom domains connected to the app.                       |

## create

```bash theme={"system"}
vetta app create storefront --type fullstack
```

| Flag     | Description                                                                                                                                          |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--type` | Required: `fullstack` or `frontend_only`. A `fullstack` app gets a managed database and is `provisioning` until it is ready — poll `vetta app show`. |

Idempotent on the name: creating an app that exists returns it. The name is a lowercase DNS label.

## deploy

```bash theme={"system"}
vetta app deploy app_3k2n8w1qv7ye5m0d4tzpxr6bhc ./dist
```

Collects every file under `<dir>` — skipping `node_modules`, `.git`, `dist` subdirectories and any
`.env*` file — and ships the tree as one deployment carrying a hash of its contents, exactly as
`naive up` does for a `deploy_dir`. The build runs after the command returns; `vetta app deployments`
is the poll.

## list

```bash theme={"system"}
vetta app list --limit 20
vetta app list --name dashboard
```

| Flag      | Description                                                                                                                                                |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--name`  | Exactly one app by name. App names are unique per organization, so this answers with one row or none — the same by-name lookup `naive up` upserts through. |
| `--limit` | Page size.                                                                                                                                                 |
| `--after` | Cursor from a previous page's `next_cursor`.                                                                                                               |

## show

```bash theme={"system"}
vetta app show app_3k2n8w1qv7ye5m0d4tzpxr6bhc
```

The `project` field is the ownership stamp `naive up` compares before it writes anything. An app
whose stamp names a different project is refused by an apply until you rename it in the config or
re-run with `--adopt`.

## deployments

```bash theme={"system"}
vetta app deployments app_3k2n8w1qv7ye5m0d4tzpxr6bhc --limit 5
```

| Flag      | Description |
| --------- | ----------- |
| `--limit` | Page size.  |

Newest first. Each row carries the `content_hash` of the tree that was shipped, which is what the
next `naive up` compares the directory against to decide whether to upload at all — equal means the
app reports `unchanged` and nothing is sent.

This is the command to run after `naive up` when a site is not live yet. The apply returns once the
deployment is accepted; the build runs after that, and its state only advances on a read.

## secrets

```bash theme={"system"}
vetta app secrets app_3k2n8w1qv7ye5m0d4tzpxr6bhc
```

Secret **values are write-only on the platform and never come back** — not here, not anywhere. What
this lists is each secret's name and an opaque hash of its value, which is exactly what lets an
apply tell a changed secret from an unchanged one without ever seeing one.

Secrets that exist on the app but are absent from the declaration's `env` are reported by `naive up`
as `unmanaged secrets: …` and left alone; this command is how you see them in full.

## domains

```bash theme={"system"}
vetta app domains app_3k2n8w1qv7ye5m0d4tzpxr6bhc
```

The domain must already exist at `vetta domain list` — connecting is pointing, never registering.
See [`vetta domain`](/docs/cli/comms).