> ## 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 > Reference for the Compose CLI manifest schema, commands, and configuration options. ## 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={"dark"} 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 ` to target by name directly, or `-m, --manifest ` (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`. ## Scripting and automation Most Compose commands can run non-interactively, which lets you drive deploys and inspections from CI, scripts, and agents. ### Authentication Every command that talks to the platform needs an auth token. The token is resolved in this order: the `-t, --token ` flag, then the `GOLDSKY_API_TOKEN` environment variable, then the token written by `goldsky login`. If none is present, the command errors: ```text theme={"dark"} Please run goldsky login, set GOLDSKY_API_TOKEN, or pass --token to the command. ``` ### JSON output Pass `--json` to any command that talks to the platform for machine-readable output: `deploy`, `callTask`, `status`, `list`, `history`, `runs`, `collections list`, `collections query`, `source`, `download`, `pause`, `resume`, `delete`, `logs`, `secret list`, `wallet create`, `wallet list`, `writeContract`, and `deployContract`. Note that `secret set` and `secret delete` do not accept it. In `--json` mode stdout carries only the result document; progress bars and other decoration are suppressed. Failures go to stderr as a JSON envelope and the command exits with code 1: ```json theme={"dark"} { "error": true, "code": "VALIDATION_FAILED", "message": "..." } ``` Error codes include `VALIDATION_FAILED`, `SECRET_MISSING`, `DEPLOY_FAILED`, `ALREADY_DEPLOYED`, `NOT_FOUND`, `WRITE_CONTRACT_FAILED`, `USAGE`, and `UNKNOWN`. `USAGE` is returned for an unknown command or for `-n` on `deploy`. ### Non-interactive behavior In a non-TTY (CI, scripts, agents), interactive prompts are skipped or error out: * `goldsky compose init ` accepts the project name as an argument and skips the prompt. Without a name it errors in non-interactive mode. * `goldsky compose deploy` aborts on a major `api_version` mismatch unless you pass `--force`. A minor mismatch defaults to continuing. * `goldsky compose clean` and `goldsky compose delete` require `-f, --force` in non-interactive mode. ### Example: scripted deploy ```bash theme={"dark"} export GOLDSKY_API_TOKEN=gs_tok_... goldsky compose deploy --json | jq -r .dashboard_url ``` ## Commands ### init \[name] 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). Pass the name as an argument to skip the prompt; the name is required in non-interactive mode. ```bash theme={"dark"} goldsky compose init my-app ``` ### start Starts your app locally. Preserves execution state from previous runs, useful for testing retry behavior and other production scenarios. By default the server binds port 4000; if that port is taken it walks up to 4009 and uses the first free port. ```bash theme={"dark"} goldsky compose start ``` Options: * `-m, --manifest ` 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)) * `--impersonate ` Impersonate wallet addresses on the local fork (e.g. `"wallet1=0xAddr1,wallet2=0xAddr2"`). Requires `--fork-chains`. See [Impersonated wallets](./context/evm/wallets#impersonated-wallets) * `-p, --port ` Bind exactly this port; fails fast if it is already in use (no walking) ### deploy Deploys the app to the cloud. On success it prints the dashboard URL, which is also available as `dashboard_url` when you pass `--json`. See [monitoring](./deploy-monitor) for more info. In a non-TTY, a major `api_version` mismatch aborts the deploy unless you pass `--force`; see [Scripting and automation](#scripting-and-automation). ```bash theme={"dark"} goldsky compose deploy ``` Options: * `-m, --manifest ` Path to manifest file (default: `compose.yaml`) * `-t, --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). * `--json` Emit the deploy result as JSON (includes `dashboard_url`) Your manifest must include an `api_version` field to deploy. All secrets referenced in the manifest must be set before deploying (see [Secrets](./secrets)). `deploy` takes the app name from the manifest, so it has no `-n, --name` flag. Passing one exits with code 1 and a one-line error instead of the full help text. An unknown command, such as `goldsky compose app`, also exits with code 1 and prints `unknown command 'app'`. ### callTask Call a task by name with a JSON payload. By default the task runs on your deployed app; pass `--env local` (or `-p, --port`) to hit a locally running server instead. ```bash theme={"dark"} # call a task on the deployed app (default) goldsky compose callTask my_task '{"foo": "bar"}' # call a task on a locally running app goldsky compose callTask my_task '{"foo": "bar"}' --env local ``` Options: * `--env ` Where to run the task (default: `cloud`). Passing `--port` implies local * `-p, --port ` Local port to call. Implies `--env local`; an error if combined with an explicit `--env cloud` * `-n, --name ` App name (alternative to `-m`) * `-m, --manifest ` Path to manifest file (default: `compose.yaml`) * `-t, --token ` Authentication token * `--json` Emit the response as JSON When calling a local server, the port is resolved in this order: the `--port` flag, then the `.compose/.port` file, then 4000. 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. ### codegen Parse ABIs in the `src/contracts/` folder and generate TypeScript classes for them. See [contracts](./context/evm/contracts) for more details. ```bash theme={"dark"} goldsky compose codegen ``` ### deployContract Compile a Solidity contract and deploy it to a chain, with gas sponsored from your app's wallet. The contract is compiled locally (no `forge` or `solc` install required) and deployed through a CREATE2 deterministic deployment proxy, so deploying the same contract from the same app produces the same address on every chain. The deployed address is printed before the transaction is sent, followed by `Submitting UserOp on ...` while the transaction is in flight. The block it was deployed in is printed on success, and the ABI is written to `src/contracts/.json` so you can run [`codegen`](#codegen) against it. With `--json`, progress lines are not printed. Imports are resolved from `node_modules/`, so OpenZeppelin and other published contracts work after a normal `npm install`. The wallet this deploys from is the same on-chain identity as `evm.wallet({ name })` in your task code for a given app and wallet name. `deployContract` and `writeContract` both work before your app's first deploy, so you can deploy a contract and use its address before anything is running. ```bash theme={"dark"} goldsky compose deployContract src/contracts/MyToken.sol \ --chain-id 84532 \ --constructor-args 0xRecipient 1000000 ``` Options: * `--chain-id ` Chain to deploy to, e.g. `8453` for Base or `84532` for Base Sepolia (required) * `--constructor-args ` Constructor arguments, space-separated (one value per argument) * `--verify` Verify the contract's source on the chain's block explorer after deploying. Opt-in because publishing source is irreversible and verification adds roughly 30 to 90 seconds * `--wallet ` Named wallet to deploy from (default: `default`). Shares identity with `evm.wallet({ name })` in task code * `--force` Deploy even if `msg.sender` usage is detected in the constructor (see note below) * `-m, --manifest ` Path to manifest file (default: `compose.yaml`) * `-t, --token ` Authentication token * `--api-server ` Override the API server URL * `--json` Emit the deploy result as JSON Because deployment routes through the CREATE2 proxy, `msg.sender` inside your constructor is the proxy address, not your wallet. If your constructor uses `msg.sender` (for example `Ownable(msg.sender)`), pass the address as an explicit constructor argument instead. The CLI warns and stops when it detects this; `--force` bypasses the check. Constructor and function arguments use forge-style syntax: space-separated, one value per argument (for example `--constructor-args 0xRecipient 1000000`). Arrays are written `[a,b]`, tuples are written `(a,b)`, and negative numbers need a leading space (for example `" -5"`). Re-deploying the identical contract from the same app fails with `CONTRACT_ALREADY_DEPLOYED` because the CREATE2 address already has code. Passing constructor arguments to a contract that has no constructor is an error. Gas spent by `deployContract` and `writeContract` is billed on your normal Goldsky bill, the same as gas used by your deployed tasks. ### writeContract Send a gas-sponsored transaction to a contract on any supported chain, using your app's wallet. Encodes calldata from a function signature and arguments, or accepts raw calldata. This is the same wallet identity your task code uses via `evm.wallet()`, so you can use it to trigger events, call admin functions, or make transfers without managing gas or keys. While the transaction is in flight the CLI prints `Submitting UserOp on ...`, and the result prints as soon as it lands. With `--json`, progress lines are not printed. `writeContract` works before your app's first deploy. Gas spent by `writeContract` is billed on your normal Goldsky bill, the same as gas used by your deployed tasks. ```bash theme={"dark"} goldsky compose writeContract \ --chain-id 84532 \ --to 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 \ --function "transfer(address,uint256)" \ --args 0xRecipient 1000000 ``` Options: * `--chain-id ` Chain to transact on (required) * `--to
` Target contract address (required) * `--function ` Function signature, e.g. `"transfer(address,uint256)"` * `--args ` Function arguments, space-separated (one value per argument) * `--data ` Raw calldata hex, as an alternative to `--function` + `--args` * `--value ` Value to send with the transaction. Accepts plain wei or an `ether`/`gwei` suffix: `1000`, `1ether`, `0.5ether`, `100gwei` * `--wallet ` Named wallet to send from (default: `default`) * `-m, --manifest ` Path to manifest file (default: `compose.yaml`) * `-t, --token ` Authentication token * `--api-server ` Override the API server URL * `--json` Emit the transaction result as JSON ### clean Deletes your local stage database (`.compose/stage.db`), wiping all local execution state and collection data. Prompts for confirmation unless `-f` is passed. In a non-TTY it aborts with `Use --force for non-interactive cleanup.` unless `-f` is passed. ```bash theme={"dark"} goldsky compose clean ``` Options: * `-f, --force` Skip the confirmation prompt * `-c, --config ` Path to manifest file (default: `compose.yaml`) ### update \[version] Update the Compose CLI. With no argument it updates to the latest version; pass a version to install a specific release. ```bash theme={"dark"} # update to the latest version goldsky compose update # install a specific version goldsky compose update 0.8.1 ``` 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={"dark"} goldsky compose status ``` Options: * `-n, --name ` App name (alternative to `-m`) * `-m, --manifest ` Path to manifest file (default: `compose.yaml`) * `-t, --token ` Authentication token * `--json` Emit JSON output (for scripts and agents) ### list List all deployed apps in your project. ```bash theme={"dark"} goldsky compose list ``` Options: * `-t, --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={"dark"} goldsky compose pause ``` Options: * `-n, --name ` / `-m, --manifest ` * `-t, --token ` * `--json` ### resume Resume a paused app. ```bash theme={"dark"} 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={"dark"} goldsky compose delete ``` Options: * `-n, --name ` / `-m, --manifest ` * `-t, --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` 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. ### logs View or tail logs from a deployed app. ```bash theme={"dark"} # 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 ` / `-m, --manifest ` * `-t, --token ` * `-f, --follow` Stream logs live * `--tail ` Number of lines to fetch (default: `100`) * `--level ` Comma-separated log levels (e.g. `error,warn`) * `--search ` Filter log lines by text * `--since ` Only show logs since a relative time (e.g. `1h`, `30m`, `7d`) * `--max-lines ` Exit after N lines (useful with `-f`) * `--timeout ` Exit after a duration (useful with `-f`) * `--json` Emit newline-delimited JSON ## Inspecting a deployed app These commands read back information about a deployed app. They accept the standard targeting flags (`-n, --name` or `-m, --manifest`) and `--json` unless noted. ### history Show the deploy history for an app. ```bash theme={"dark"} goldsky compose history ``` Options: * `-n, --name ` / `-m, --manifest ` * `-t, --token ` Authentication token * `--limit ` Number of records to show (default: 20, server caps at 100) * `--offset ` Number of records to skip (default: 0) * `--include-failures` Include failed deploys in the list * `--json` Emit JSON output When the list is truncated, the output prints the visible range, for example: `Showing 6-7 of 42 records. Use --limit and --offset to page.` ### runs \[runId] List task runs for an app, or show one run's detail when you pass a run id. ```bash theme={"dark"} # list recent runs goldsky compose runs # show one run's detail goldsky compose runs 01HV8X2K1QZ9F4N1V3M2P7B6 ``` Options: * `-n, --name ` / `-m, --manifest ` * `-t, --token ` Authentication token * `--limit ` Number of runs to show * `--offset ` Number of runs to skip * `--task ` Filter to runs of a single task * `--status ` Filter by run status * `--since ` Only show runs since a relative time (e.g. `1h`, `30m`, `7d`) * `--until ` Only show runs before a relative time * `--json` Emit JSON output ### collections list List the collection names for an app. ```bash theme={"dark"} goldsky compose collections list ``` Options: * `-n, --name ` / `-m, --manifest ` * `-t, --token ` Authentication token * `--json` Emit JSON output ### collections query \[collectionName] Query documents in a collection. The collection name is required. ```bash theme={"dark"} goldsky compose collections query prices --filter '{"symbol": "BTC"}' --limit 10 ``` Options: * `-n, --name ` / `-m, --manifest ` * `-t, --token ` Authentication token * `--filter ` Filter documents by a JSON predicate * `--limit ` Number of documents to return (default: 100, maximum: 1000) * `--offset ` Number of documents to skip * `--json` Emit JSON output ### source \[taskName] Print the deployed source for an app. With no argument it lists the deployed files; with a task name it prints that task's source. It never writes to disk. ```bash theme={"dark"} # list deployed files goldsky compose source # print one task's source goldsky compose source price_fetcher ``` Options: * `-n, --name ` / `-m, --manifest ` * `-t, --token ` Authentication token * `--json` Emit JSON output ### download Download the deployed source archive as `.zip` by default. Use `-o, --output ` to choose a destination; the command refuses to overwrite an existing file. A downloaded app runs locally as-is: `compose start` detects the pre-bundled task files and runs them without re-bundling. ```bash theme={"dark"} goldsky compose download goldsky compose download -o ./my-app.zip ``` Options: * `-n, --name ` / `-m, --manifest ` * `-t, --token ` Authentication token * `-o, --output ` Output path (default: `.zip`) * `--json` Emit JSON output ## Wallet management ### wallet create Create a named wallet for this app and print its address. Works before the app's first deploy, so you can create a wallet, fund it, or pass its address as a constructor argument to `deployContract` before anything is running. ```bash theme={"dark"} # 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 to manifest file (default: `compose.yaml`); the app name is read from here * `--env ` Where to create the wallet (default: `cloud`) * `-t, --token ` * `--json` Emit the wallet as JSON 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. Returns an empty list for an app that has never deployed. ```bash theme={"dark"} goldsky compose wallet list goldsky compose wallet list --env local ``` Options: * `-m, --manifest ` Path to manifest file (default: `compose.yaml`) * `--env ` (default: `cloud`) * `-t, --token ` * `--json` Emit the wallets as JSON ## Secrets See [Secrets](./secrets) for the full workflow. ### secret set Set or update a secret. See [Secrets](./secrets) for full details. ```bash theme={"dark"} # 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 ` Secret value (required) * `--env ` Where to store the secret (default: `cloud`) * `--redeploy` After setting, redeploy the app so the new value takes effect * `-n, --name ` / `-m, --manifest ` * `-t, --token ` 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. ### secret delete Delete a secret. ```bash theme={"dark"} goldsky compose secret delete MY_SECRET goldsky compose secret delete MY_SECRET --env local ``` Options: * `--env ` Where to delete from (default: `cloud`) * `-n, --name ` / `-m, --manifest ` * `-t, --token ` ### secret list List the names of cloud secrets set for this app. Secret values are never shown; see [How secrets are stored](./secrets#how-secrets-are-stored). ```bash theme={"dark"} goldsky compose secret list ``` Options: * `-n, --name ` / `-m, --manifest ` * `-t, --token ` * `--json` Emit the secret names as JSON ## Related topics - [Compose app manifest configuration reference](/compose/app-configuration.md) - [CLI Reference](/reference/cli.md)