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

# Compose CLI Reference

## Manifest

The Compose App's manifest is a YAML file with the following schema.  The manifest holds all the relevant information about the Compose App and its tasks.
All compose commands will reference your manifest and pick up the configuration there. See full manifest configuration docs [here](./app-configuration).

### Example

```yaml theme={null}
name: "my_app"
api_version: "stable"
secrets:
  - MY_SECRET
env:
  local:
    MY_VAR: "foo"
  cloud:
    MY_VAR: "bar"
tasks:
  - name: "price_fetcher"
    path: "./tasks/fetch_price.ts"
    triggers:
      - type: "cron"
        expression: "* * * * *" # Run every minute
      - type: "http"
        authentication: "auth_token"
    retry_config:
      max_attempts: 3
      initial_interval_ms: 1000
      backoff_factor: 2
  - name: "data_processor"
    path: "./tasks/process_data.ts"
```

## App targeting

Most commands that operate on a deployed app accept either `-n, --name <app>` to target by name directly, or `-m, --manifest <path>` (default `compose.yaml`) to read the name from a manifest. If neither is provided and no `compose.yaml` is present, the command errors. A few commands (`deploy`, `wallet create`, `wallet list`) only support `-m, --manifest`.

## Commands

### init

Prompts you for a project name and scaffolds a folder of that name containing a working Compose app (a Bitcoin price oracle example you can run right away).

```bash theme={null}
goldsky compose init
```

### start

Starts your app locally. Preserves execution state from previous runs, useful for testing retry behavior and other production scenarios.

```bash theme={null}
goldsky compose start
```

Options:

* `-m, --manifest <path>` Path to manifest file (default: `compose.yaml`)
* `--fork-chains` Fork all chains referenced in contract interactions locally for testing — see [forking](./environments#forking-for-local-compose-development)

### deploy

Deploys the app to the cloud. From there you can monitor it at `https://app.goldsky.com/dashboard/compose/{appName}`.
See [monitoring](./deploy-monitor) for more info.

```bash theme={null}
goldsky compose deploy
```

Options:

* `-m, --manifest <path>` Path to manifest file (default: `compose.yaml`)
* `-t, --token <token>` Authentication token for deployment
* `-f, --force` Skip version compatibility prompts
* `--sync-env` Upload secrets from your local `.env` to the cloud before deploying, in one step. See [Secrets](./secrets).

<Note>
  Your manifest must include an `api_version` field to deploy. All secrets referenced in the manifest must be set before deploying (see [Secrets](./secrets)).
</Note>

### callTask

Trigger a task on your locally-running app by name with a JSON payload. Useful for testing tasks during development.

```bash theme={null}
goldsky compose callTask my_task '{"foo": "bar"}'
```

<Note>
  Both the task name and the JSON payload are required. The payload must be valid JSON — `{foo: "bar"}` is invalid, use `{"foo": "bar"}` (or `'{}'` if the task takes no input) instead.
</Note>

### codegen

Parse ABIs in the `src/contracts/` folder and generate TypeScript classes for them.
See [contracts](./context/evm/contracts) for more details.

```bash theme={null}
goldsky compose codegen
```

### clean

Deletes your local stage database (`.compose/stage.db`), wiping all local execution state and collection data. Prompts for confirmation unless `-f` is passed.

```bash theme={null}
goldsky compose clean
```

Options:

* `-f, --force` Skip the confirmation prompt
* `-c, --config <path>` Path to manifest file (default: `compose.yaml`)

### update

Update the Compose CLI to the latest version.

```bash theme={null}
goldsky compose update
```

Options:

* `--preview` Install the latest preview build from `main` instead of the current stable release

See [Release channels](./app-configuration#release-channels) for the difference between `stable` and `preview`.

## App lifecycle

For full examples, see [App lifecycle](./app-lifecycle).

### status

Show the status of a deployed app.

```bash theme={null}
goldsky compose status
```

Options:

* `-n, --name <name>` App name (alternative to `-m`)
* `-m, --manifest <path>` Path to manifest file (default: `compose.yaml`)
* `-t, --token <token>` Authentication token
* `--json` Emit JSON output (for scripts and agents)

### list

List all deployed apps in your project.

```bash theme={null}
goldsky compose list
```

Options:

* `-t, --token <token>` Authentication token
* `--json` Emit JSON output

### pause

Pause a deployed app. Cron triggers stop firing and HTTP triggers return an error until the app is resumed.

```bash theme={null}
goldsky compose pause
```

Options:

* `-n, --name <name>` / `-m, --manifest <path>`
* `-t, --token <token>`
* `--json`

### resume

Resume a paused app.

```bash theme={null}
goldsky compose resume
```

Options: same as `pause`.

### delete

Delete a deployed app. Interactively prompts you to type the app name to confirm, then asks whether to also delete the app's hosted Postgres database (unless `--delete-database` is already set). Pass `--force` to skip both prompts — required for non-interactive use. In non-TTY environments without `--force`, the command errors out.

```bash theme={null}
goldsky compose delete
```

Options:

* `-n, --name <name>` / `-m, --manifest <path>`
* `-t, --token <token>`
* `-f, --force` Skip confirmation prompts (required for non-interactive use, e.g. CI)
* `--delete-database` Also delete the app's hosted Postgres database
* `--json`

<Warning>
  Deleting an app (and especially its database) is permanent. See [Deleting a Compose app](./deploy-monitor#deleting-a-compose-app) for the full behavior including pipeline safety checks.
</Warning>

### logs

View or tail logs from a deployed app.

```bash theme={null}
# show the last 100 log lines
goldsky compose logs

# tail logs live, filtered to errors and warnings
goldsky compose logs -f --level error,warn

# show logs from the last hour
goldsky compose logs --since 1h

# show 500 lines and exit
goldsky compose logs --max-lines 500
```

Options:

* `-n, --name <name>` / `-m, --manifest <path>`
* `-t, --token <token>`
* `-f, --follow` Stream logs live
* `--tail <lines>` Number of lines to fetch (default: `100`)
* `--level <levels>` Comma-separated log levels (e.g. `error,warn`)
* `--search <text>` Filter log lines by text
* `--since <duration>` Only show logs since a relative time (e.g. `1h`, `30m`, `7d`)
* `--max-lines <count>` Exit after N lines (useful with `-f`)
* `--timeout <duration>` Exit after a duration (useful with `-f`)
* `--json` Emit newline-delimited JSON

## Wallet management

### wallet create

Create a named wallet for this app and print its address. Useful for pre-creating wallets so you can fund them before your tasks first run.

```bash theme={null}
# create a cloud wallet (default)
goldsky compose wallet create my_wallet

# create a local wallet in your stage DB
goldsky compose wallet create my_wallet --env local
```

Options:

* `-m, --manifest <path>` Path to manifest file (default: `compose.yaml`) — the app name is read from here
* `--env <local|cloud>` Where to create the wallet (default: `cloud`)
* `-t, --token <token>`

The wallet address is printed to stdout so you can pipe it into other commands or scripts.

### wallet list

List wallets that have been created for this app.

```bash theme={null}
goldsky compose wallet list
goldsky compose wallet list --env local
```

Options:

* `-m, --manifest <path>` Path to manifest file (default: `compose.yaml`)
* `--env <local|cloud>` (default: `cloud`)
* `-t, --token <token>`

## Secrets

See [Secrets](./secrets) for the full workflow.

### secret set

Set or update a secret. See [Secrets](./secrets) for full details.

```bash theme={null}
# set a cloud secret (default)
goldsky compose secret set MY_SECRET --value my-secret-value

# set a local secret (writes to .env)
goldsky compose secret set MY_SECRET --value my-secret-value --env local

# set a cloud secret and redeploy the app to pick it up
goldsky compose secret set MY_SECRET --value my-secret-value --redeploy
```

Options:

* `--value <value>` Secret value (required)
* `--env <local|cloud>` Where to store the secret (default: `cloud`)
* `--redeploy` After setting, redeploy the app so the new value takes effect
* `-n, --name <app>` / `-m, --manifest <path>`
* `-t, --token <token>`

<Note>
  Secret names must be SCREAMING\_SNAKE\_CASE. A running app only picks up secret changes after a redeploy — pass `--redeploy` or run `goldsky compose deploy` yourself.
</Note>

### secret delete

Delete a secret.

```bash theme={null}
goldsky compose secret delete MY_SECRET
goldsky compose secret delete MY_SECRET --env local
```

Options:

* `--env <local|cloud>` Where to delete from (default: `cloud`)
* `-n, --name <app>` / `-m, --manifest <path>`
* `-t, --token <token>`

### secret list

List all cloud secrets set for this app.

```bash theme={null}
goldsky compose secret list
```

Options:

* `-n, --name <app>` / `-m, --manifest <path>`
* `-t, --token <token>`