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

> ## Agent Instructions
> Unkey is two separate products. Compute builds, deploys, and runs apps behind a gateway. API Management issues API keys, enforces rate limits, manages identities and permissions, and reports usage. Say which product a page belongs to; a reader can use either without the other.
> Every Unkey API endpoint is an HTTP POST to https://api.unkey.com/v2/{service}.{procedure} with a root key in the Authorization: Bearer header. Root keys are workspace scoped.
> Error codes have the form err:{system}:{category}:{specific} and each has a page at /errors/{system}/{category}/{specific}.
> The word environment means production or preview in Compute. Rate limiting has four meanings on this site; the glossary lists them.

# unkey api apps create-app

> Create an app in a project, optionally connected to a GitHub repository.

<Note>
  You need a root key with the permissions listed on this page. Create one in the dashboard under **Settings > Root Keys**. See [Permission reference](/docs/platform/root-keys/permissions-legacy) for every permission.
</Note>

Create an <Tooltip tip="A Compute app: a deployable service inside a project. Not your application in general.">app</Tooltip> inside a project. The app is created with a `production` and a `preview` <Tooltip tip="A production or preview environment of a Compute app, not the dashboard label on a key.">environment</Tooltip>.

The slug is what you pass to later `--app` flags. It must be unique within the project, or you get a 409 conflict.

Pass exactly one source:

* `--git` for a GitHub repository. Pass a `repository` to connect it now (the [Unkey GitHub App](/docs/compute/cli/github/install-app) must be installed first), or pass `--git='{}'` and connect one later with [update-app](/docs/compute/cli/apps/update-app).
* `--oci` for a prebuilt image, if you already build images elsewhere.

## Usage

```bash theme={"system"}
unkey api apps create-app --project=<project> --name=<name> --slug=<slug> (--git=<json> | --oci=<json>)
```

## Flags

<ParamField body="--git" type="string">
  GitHub repository connection as a JSON object, for example `{"repository":"unkeyed/api","defaultBranch":"main"}`. Both fields are optional, so `{}` creates a Git app with no repository yet; `defaultBranch` requires `repository`. Mutually exclusive with `--oci`.
</ParamField>

<ParamField body="--oci" type="string">
  OCI image source as a JSON object with a required `image` field, for example `{"image":"ghcr.io/acme/payments:v1.2.3"}`. The reference needs an explicit tag or digest and is at most 256 characters. Mutually exclusive with `--git`.
</ParamField>

<ParamField body="--name" type="string" required>
  Human-readable name for the app, 1 to 256 characters.
</ParamField>

<ParamField body="--project" type="string" required>
  Project ID or slug. Both forms resolve to the same project.
</ParamField>

<ParamField body="--slug" type="string" required>
  Stable app slug, unique within the project. 3 to 255 characters matching `^[a-zA-Z0-9_-]+$`. Used in `--app` flags and in generated deployment hostnames.
</ParamField>

### Shared flags

Every `unkey api` command accepts these; [CLI output and shared flags](/docs/platform/cli/output-and-flags) describes them in full.

<ParamField body="--body" type="string">
  A JSON document sent as the request body instead of building it from the flags above. It is mutually exclusive with the request-building flags, and unknown fields are rejected locally. See [Send a raw body](/docs/platform/cli/output-and-flags#send-a-raw-body).
</ParamField>

<ParamField body="--root-key" type="string">
  Root key for the request. Falls back to `UNKEY_ROOT_KEY`, then to the config file written by `unkey auth login`. See [CLI authentication](/docs/platform/cli/authentication).
</ParamField>

<ParamField body="--api-url" type="string" default="https://api.unkey.com">
  Base URL of the API. Falls back to `UNKEY_API_BASE_URL`. You don't normally need to set it.
</ParamField>

<ParamField body="--config" type="string" default="~/.unkey/config.toml">
  Path of the TOML file that `unkey auth login` writes. Falls back to `UNKEY_CONFIG`.
</ParamField>

<ParamField body="--output" type="string">
  Output format. Falls back to `UNKEY_OUTPUT`. Set `json` to print the full response envelope (`meta` and `data`) for piping; any other value prints the request ID followed by `data`.
</ParamField>

## Required permissions

Your root key needs one of:

* `project.*.create_app` (apps in any project)
* `project.<project_id>.create_app` (apps in a specific project)

If `--git` includes a `repository`, your key also needs `app.*.connect_repository`. `--git='{}'` doesn't.

Without a matching permission the API answers 403 and the CLI prints `Permission denied:` followed by the detail. See [Root key permissions](/docs/platform/root-keys/permissions) for the full catalog.

## Examples

Create an app connected to a repository:

```bash theme={"system"}
unkey api apps create-app --project=payments --name='Payments API' --slug=payments-api --git='{"repository":"unkeyed/api","defaultBranch":"main"}'
```

Create a Git app now and connect the repository later:

```bash theme={"system"}
unkey api apps create-app --project=payments --name='Payments API' --slug=payments-api --git='{}'
```

Create an app from a prebuilt image:

```bash theme={"system"}
unkey api apps create-app --project=payments --name='Payments API' --slug=payments-api --oci='{"image":"ghcr.io/acme/payments:v1.2.3"}'
```

Send the request body as JSON:

```bash theme={"system"}
unkey api apps create-app --body='{"project":"payments","name":"Payments API","slug":"payments-api","oci":{"image":"ghcr.io/acme/payments:v1.2.3"}}' --output=json
```

## API endpoint

The command calls [`POST /v2/apps.createApp`](/docs/compute/api-reference/apps/create-app) and prints its response. The request fields carry the same names as the flags in camelCase, which is the shape `--body` expects.

## Related

<Columns cols={2}>
  <Card title="Projects, apps, and environments" href="/docs/compute/concepts/projects-apps-environments">
    How the three objects nest and how slugs and IDs are resolved.
  </Card>

  <Card title="Deploy from GitHub" href="/docs/compute/get-started/deploy-from-github">
    Connect a repository and ship the first deployment.
  </Card>
</Columns>