# Execution and deployment

Source: /docs/reference/cli/execution.md

A saved resource version is code the platform can execute. Building prepares its runtime/artifact, running invokes it, and deploying selects a production version. Choose the operation that produces the state you need.

| Command | Supported resource / result |
| --- | --- |
| `run TYPE NAME` | API, transform, or sync preview execution |
| `test TYPE NAME` | API or transform mock tests |
| `build TYPE NAME` | API runtime, transform image, or hosted app preview |
| `deploy TYPE NAME` | Deploy latest committed or an explicit saved version |
| `upgrade TYPE NAME` | Deploy latest committed version |
| `undeploy TYPE NAME` | Clear deployment or disable app hosting |
| `job JOB_ID` | Read execution/processing status and results |
| `logs JOB_ID` | Read execution or build logs |

Deployment supports APIs, transforms, syncs, connectors, agents, and apps. Databases use their own [migration workflow](/docs/reference/cli/data#inspect-and-approve-database-migrations).

## Run saved source [#run-saved-source]

```sh
vortexify build api normalize --wait
vortexify test api normalize --wait
vortexify run api normalize --inputs-file inputs.json --wait --json
vortexify run transform customer_totals --wait
vortexify run sync shop/orders --wait
```

Names can be registered names or IDs. Sync names can be connector-qualified. Save source changes with commit before execution. `--inputs-file` is available on run and contains a JSON object matching scalar runtime inputs; it does not replace managed dependency declarations.

Run, test, build, and deploy accept `--version N` to select saved source. Upgrade always selects the latest committed version and has no `--version` flag. Undeploy has no version selector.

CLI run submits preview work. An API invocation or sync extraction can still have real effects; preview identifies the execution path, not a dry run. Use mocks for tests of external writes and `Sync.preview()` for disposable source samples.

## Rebuild affected previews [#rebuild-affected-previews]

`run` and `build` expose `--rebuild-downstream` for an explicit dependent-preview plan. The server executes selected work in dependency order and reports downstream jobs on the root result. Use a transform run to publish its output before rebuilding consumers; transform build with downstream rebuilding is rejected. Tests do not rebuild downstream resources, and syncs only support run.

This prepares preview work. It does not automatically upgrade production deployments.

## Follow existing work [#follow-existing-work]

```sh
vortexify job JOB_ID --wait --json
vortexify logs JOB_ID
```

Run/build/test/deployment and job/log commands support `--json`, `--wait`, and `--timeout DURATION`. The default wait limit is 30 minutes. A timeout or interrupted wait stops observation; reuse the job ID to resume instead of resubmitting work.

Inspect both status and processing completion. A job may still be publishing output or waiting for selected downstream previews after its own code has finished. Execution submission and job inspection report failed/stopped execution with a nonzero exit. Logs retrieves diagnostic output even for a failed run; inspect validation/test reports separately where relevant.

The platform mirrors these distinctions in **Playground → History → Output / Processing / Logs / JSON** for APIs and transforms, and **Runs & logs** for other resources. Processing links related runtime preparation, schema discovery, and downstream jobs.

For SQL investigations, use [analyze](/docs/reference/cli/data#run-an-analysis-query), which has its own flags and saved-result retrieval path.

## Publish and update [#publish-and-update]

```sh
vortexify deploy api normalize --version 3 --wait
vortexify deploy app dashboard --subdomain orders --wait
vortexify upgrade api normalize --wait
vortexify undeploy app dashboard --wait
```

`--subdomain` is available on app deploy/upgrade and selects the app hostname label, subject to server configuration and plan features. New source commits do not replace a deployed version automatically.

Deploying a transform or sync selects its production source; it does not immediately execute it. Prepare the first production output before publishing dependent APIs/apps. The current platform Playground submits previews. Explicit production transform execution is available through a published app's client or the authenticated `artifacts/functions/start_transform_function` service with `preview: false`, requiring editor access.

See [Publish your app](/docs/building/publish-your-app) for dependency order, and [tables/publications](/docs/data/tables) for which outputs consumers read.

When container logs cannot be retrieved, `logs` reports their unavailability alongside a recorded pod failure or eviction reason when available. Log retrieval failure and workload failure are separate. A timed-out wait exits nonzero and leaves backend work running; observe the existing job ID rather than assuming it was canceled.