thyme run

thyme run evaluates the selected task with local arguments, secrets, and storage. It prints logs, the task result, available execution statistics, and produced storage. It does not broadcast transactions.

thyme run [task] [--simulate] [--persist] [--simulate-callbacks] [--callback <outcome>]

Run from a Thyme project with Deno and project dependencies installed. Set SIMULATE_ACCOUNT to a valid EVM address for ctx.account, including tasks that do not use the client. Without a terminal, pass the task name explicitly.

Options

Inputs and environment

• args.json supplies raw input; defineTask validates and transforms it.
• storage.json supplies initial JSON state. Missing files default to {}; malformed or unreadable files are fatal.
• Root .env loads first without overriding existing process variables. Task .env loads afterward with override enabled.
• Keys loaded from those files become ctx.secrets, excluding reserved and unsafe keys. Arbitrary process environment variables are not automatically injected as secrets.
• RPC_URL and SIMULATE_ACCOUNT may also come directly from the process environment. The local public client is created lazily, so RPC is unnecessary if your task never accesses it.

See configuration for the reserved keys and paths. Keep real secret values out of output: local logging does not provide cloud redaction.

Sandbox behavior

The subprocess uses Deno with --no-prompt and manual node_modules resolution. It can read its task directory, project dependencies, and selected project configuration files. Network access is enabled. The CLI configures a V8 old-space limit of 128 MB; this is not a guarantee that the entire process uses at most that much memory.

The current local runner has no explicit wall-clock timeout or watch mode. Interrupt a stuck task and rerun after changes. Cloud runtime limits are documented separately in local versus cloud.

Call simulation

thyme run my-task --simulate

The CLI first attempts viem simulateCalls / eth_simulateV1. If that fails, it reports the problem and falls back to individual eth_call requests with best-effort gas estimates. Independent calls do not share state, so an approve-then-deposit sequence cannot be verified faithfully by that fallback.

The local sender, gas context, smart-account behavior, and submission path may differ from the cloud. Select an appropriate RPC and account, and use cloud executable simulation before relying on profile-specific execution behavior.

Callback simulation

thyme run my-task --callback onSuccess
thyme run my-task --callback onFail:reverted
thyme run my-task --callback onFail:submit
thyme run my-task --callback onFail:timeout

The task must define the selected callback and return canExec: true; otherwise callback simulation is unavailable or skipped. onSkip and onError are invoked naturally during evaluation. Fabricated payloads are for checking handler logic and do not establish an on-chain result. See lifecycle callbacks.

Persisting storage

thyme run counter --persist

Without --persist, produced storage is printed only. Storage must be a valid JSON object within the 100 MiB local limit. With callback simulation, eligible callback output is also written back. --persist is a local file operation, independent of whether an RPC preview succeeded; treat that file as local development state.

Known limitations

CLI 0.10.0 has a confirmed missing readFile import in its local permission-manifest loader. When permissions.json exists, thyme run can stop with readFile is not defined before evaluating the task. Upload uses a separate loader and still validates/packages the manifest. Preserve the declaration for releases; this error requires a CLI fix, not a manifest format change.

Permission diagnostics, RPC simulation failures, and fabricated callback failures are printed but do not reliably produce a failing exit code. A zero exit status from --simulate is not a deployment gate. Local ordinary task failures do exit unsuccessfully.

Next steps

Use local testing to exercise your logic, then upload a release and configure its executable.