Compose CLI Reference - Goldsky Docs

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.

Example

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.

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 <token> flag, then the GOLDSKY_API_TOKEN environment variable, then the token written by goldsky login. If none is present, the command errors:

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:

{ "error": true, "code": "VALIDATION_FAILED", "message": "..." }

Error codes include VALIDATION_FAILED, SECRET_MISSING, DEPLOY_FAILED, ALREADY_DEPLOYED, NOT_FOUND, WRITE_CONTRACT_FAILED, and UNKNOWN.

Non-interactive behavior

In a non-TTY (CI, scripts, agents), interactive prompts are skipped or error out:

goldsky compose init <name> 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

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.

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.

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
--impersonate <mappings> Impersonate wallet addresses on the local fork (e.g. "wallet1=0xAddr1,wallet2=0xAddr2"). Requires --fork-chains. See Impersonated wallets
-p, --port <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 for more info. In a non-TTY, a major api_version mismatch aborts the deploy unless you pass --force; see Scripting and automation.

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.
--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).

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.

# 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 <local|cloud> Where to run the task (default: cloud). Passing --port implies local
-p, --port <port> Local port to call. Implies --env local; an error if combined with an explicit --env cloud
-n, --name <app> App name (alternative to -m)
-m, --manifest <path> Path to manifest file (default: compose.yaml)
-t, --token <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 for more details.

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. The block it was deployed in is printed on success, and the ABI is written to src/contracts/<ContractName>.json so you can run codegen against it. 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.

goldsky compose deployContract src/contracts/MyToken.sol \
  --chain-id 84532 \
  --constructor-args 0xRecipient 1000000

Options:

--chain-id <id> Chain to deploy to, e.g. 8453 for Base or 84532 for Base Sepolia (required)
--constructor-args <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 <name> 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> Path to manifest file (default: compose.yaml)
-t, --token <token> Authentication token
--api-server <url> 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. 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.

goldsky compose writeContract \
  --chain-id 84532 \
  --to 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 \
  --function "transfer(address,uint256)" \
  --args 0xRecipient 1000000

Options:

--chain-id <id> Chain to transact on (required)
--to <address> Target contract address (required)
--function <signature> Function signature, e.g. "transfer(address,uint256)"
--args <args> Function arguments, space-separated (one value per argument)
--data <hex> Raw calldata hex, as an alternative to --function + --args
--value <wei> Value to send with the transaction. Accepts plain wei or an ether/gwei suffix: 1000, 1ether, 0.5ether, 100gwei
--wallet <name> Named wallet to send from (default: default)
-m, --manifest <path> Path to manifest file (default: compose.yaml)
-t, --token <token> Authentication token
--api-server <url> 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.

goldsky compose clean

Options:

-f, --force Skip the confirmation prompt
-c, --config <path> 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.

# 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 for the difference between stable and preview.

App lifecycle

For full examples, see App lifecycle.

status

Show the status of a deployed app.

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.

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.

goldsky compose pause

Options:

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

resume

Resume a paused app.

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.

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

Deleting an app (and especially its database) is permanent. See Deleting a Compose app for the full behavior including pipeline safety checks.

logs

View or tail logs from a deployed app.

# 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

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.

goldsky compose history

Options:

-n, --name <name> / -m, --manifest <path>
-t, --token <token> Authentication token
--limit <n> Number of records to show (default: 20, server caps at 100)
--offset <n> 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.

# list recent runs
goldsky compose runs

# show one run's detail
goldsky compose runs 01HV8X2K1QZ9F4N1V3M2P7B6

Options:

-n, --name <name> / -m, --manifest <path>
-t, --token <token> Authentication token
--limit <n> Number of runs to show
--offset <n> Number of runs to skip
--task <name> Filter to runs of a single task
--status <success|error|pending> Filter by run status
--since <duration> Only show runs since a relative time (e.g. 1h, 30m, 7d)
--until <duration> Only show runs before a relative time
--json Emit JSON output

collections list

List the collection names for an app.

goldsky compose collections list

Options:

-n, --name <name> / -m, --manifest <path>
-t, --token <token> Authentication token
--json Emit JSON output

collections query [collectionName]

Query documents in a collection. The collection name is required.

goldsky compose collections query prices --filter '{"symbol": "BTC"}' --limit 10

Options:

-n, --name <name> / -m, --manifest <path>
-t, --token <token> Authentication token
--filter <json> Filter documents by a JSON predicate
--limit <n> Number of documents to return (default: 100, maximum: 1000)
--offset <n> 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.

# list deployed files
goldsky compose source

# print one task's source
goldsky compose source price_fetcher

Options:

-n, --name <name> / -m, --manifest <path>
-t, --token <token> Authentication token
--json Emit JSON output

download

Download the deployed source archive as <app>.zip by default. Use -o, --output <path> 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.

goldsky compose download
goldsky compose download -o ./my-app.zip

Options:

-n, --name <name> / -m, --manifest <path>
-t, --token <token> Authentication token
-o, --output <path> Output path (default: <app>.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.

# 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>
--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.

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>
--json Emit the wallets as JSON

Secrets

See Secrets for the full workflow.

secret set

Set or update a secret. See Secrets for full details.

# 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>

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.

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 the names of cloud secrets set for this app. Secret values are never shown; see How secrets are stored.

goldsky compose secret list

Options:

-n, --name <app> / -m, --manifest <path>
-t, --token <token>
--json Emit the secret names as JSON

​Manifest

​Example

​App targeting

​Scripting and automation

​Authentication

​JSON output

​Non-interactive behavior

​Example: scripted deploy

​Commands

​init [name]

​start

​deploy

​callTask

​codegen

​deployContract

​writeContract

​clean

​update [version]

​App lifecycle

​status

​list

​pause

​resume

​delete

​logs

​Inspecting a deployed app

​history

​runs [runId]

​collections list

​collections query [collectionName]

​source [taskName]

​download

​Wallet management

​wallet create

​wallet list

​Secrets

​secret set

​secret delete

​secret list

Manifest

Example

App targeting

Scripting and automation

Authentication

JSON output

Non-interactive behavior

Example: scripted deploy

Commands

init [name]

start

deploy

callTask

codegen

deployContract

writeContract

clean

update [version]

App lifecycle

status

list

pause

resume

delete

logs

Inspecting a deployed app

history

runs [runId]

collections list

collections query [collectionName]

source [taskName]

download

Wallet management

wallet create

wallet list

Secrets

secret set

secret delete

secret list