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

# Managing Apps

> Create, configure, and manage apps using the CLI and dashboard.

The [CLI](/cli) is the primary interface for managing apps. The dashboard also provides limited app management. To see all available commands, run `nuon apps --help`.

## Creating an App

Create a directory for your app config files, then create the app:

```sh theme={null}
mkdir your-app
cd your-app
nuon apps create --name=your-app
```

The app name should match the directory name.

## Pinning an App

Pin an app to set its ID as the default for all app commands, avoiding the need to pass `-a` each time:

```sh theme={null}
nuon apps select
nuon apps current  # show the currently pinned app
```

<Note>Examples below assume you have run `nuon apps select` first.</Note>

## Common Commands

```sh theme={null}
nuon apps list              # list all apps
nuon apps get               # get info about the pinned app
nuon apps rename --name=new-name  # rename an app
```

## Syncing Configuration

Sync uploads your TOML config files to the Nuon control plane and triggers builds for any changed components:

```sh theme={null}
nuon apps sync
```

If component TOML files or related files (e.g., Helm `values.yaml`) have changed, a new build is triggered during sync. If component source files have changed, push those changes to your git repo first, then build the component manually using the dashboard or CLI.

## Viewing Configuration

```sh theme={null}
nuon apps configs          # list all config versions
nuon apps runner-config    # print runner config
nuon apps sandbox-config   # print sandbox config
nuon apps input-config     # print input config
```

<Note>
  The output of `runner-config`, `sandbox-config`, and `input-config` is JSON. Pipe through `jq` or `python -m json.tool` for readability.
</Note>

## Metadata

Add metadata to your app via a `metadata.toml` file in the app root directory. This metadata is used in installers and the dashboard:

```toml metadata.toml theme={null}
display_name = "Your App"
description  = "A short description of your app."
readme       = "./README.md"
```

The `readme` field points to a Markdown file rendered in the dashboard for each install. See the [Using READMEs](/guides/using-readmes) guide for details.

### Label colors

Give labels custom colors in the dashboard with a `label_colors` table in `metadata.toml`. Keys are label key names; values are hex color codes:

```toml metadata.toml theme={null}
[label_colors]
env      = "#FF5733"
region   = "#33FF57"
customer = "#3357FF"
```

The colors apply wherever those label keys appear in the dashboard — on apps, installs, and components. You can also set label colors directly in the dashboard; either source can be updated later, and a sync will reconcile the values from your config.

### Default labels

Apply labels to every install of an app with a `default_labels` table in `metadata.toml`:

```toml metadata.toml theme={null}
[default_labels]
service_tier   = "{{ .nuon.inputs.service_tier }}"
```

Values can use the [interpolation syntax](/guides/using-variables) to render per install from install state,
and re-render automatically as that state changes.

Default labels are owned by the app config. They locked on each install and cannot be updated manually or via install config.
To change or remove a default label, you must edit `default_labels` in the app config. The change will propagate to each install when the new version of that app is released.