> ## Documentation Index
> Fetch the complete documentation index at: https://docs.synq.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Workspace suites
> From a local file to a scheduled production deployment — Development, Production, and what each step preserves
A suite that only runs on your machine is a useful tool. A suite in your workspace is a monitored one: versioned, runnable by anyone with access, schedulable, and wired into assets, checks, issues and alerts.
Two stages, in the app under **Health → Reconciliations**:
| Stage | What lives there | How a run starts |
| --------------- | ------------------------------------------------------------------- | ---------------------------------------- |
| **Development** | Stored, versioned suites. The shared draft. | On demand only |
| **Production** | Deployments — immutable snapshots with a schedule and run settings. | Schedule, API trigger, or the Run button |
## Save to Development
```bash theme={null}
synq-recon auth whoami # confirm the workspace first
synq-recon upload-config suite.yaml --change-summary "Add inventory reconciliation"
```
Prints the suite id. Requires `SCOPE_RECON_EDIT`.
**Development suites → New suite** opens a four-step wizard: **Data Sources**, **Comparison**, **Suite Info**, **Review**. It searches your catalog, so you can pick a table you have already catalogued rather than typing warehouse coordinates.
**Upload Suite Config** takes a whole suite as pasted or uploaded YAML — which is how you get anything the wizard does not cover. [What the wizard covers](/reconciliation/authoring-suites#what-the-wizard-covers-and-what-needs-yaml) is the map.
Every save creates a new **version**. The change summary is what makes the version history readable six months later.
```bash theme={null}
synq-recon suite list
synq-recon suite versions
synq-recon suite yaml > suite.yaml # read it back as editable YAML
synq-recon suite delete # soft delete
```
`suite yaml` is the round-trip that makes a stored suite editable again — including one someone else created in the wizard. Fetch it, edit the file, `upload-config` it back. This is also the recipe for copying a suite between workspaces.
## Bind connections to integrations
A backend run does not see the credentials in your YAML. It uses **integrations** — the warehouse credentials your workspace already manages.
```bash theme={null}
synq-recon connections remote list # what is available, with ids
synq-recon connections remote list --recon-deployable # only the ones recon can use
```
By default each connection name binds to the integration whose id matches it. Map them explicitly when the names differ:
```bash theme={null}
synq-recon run-remote --map gateway= --map warehouse=
```
In the app this is the **Bind suite connections to integrations** dialog.
`N connection(s) could not be bound to an integration` means a suite connection has no matching integration, or the integration is not enabled for reconciliation. Check the names with `connections remote list --recon-deployable`, or bind explicitly with `--map`.
Read [connection vs integration](/reconciliation/concepts#connection-vs-integration) once if that distinction is new — the same YAML key means two different things in the two stages, and it is the most common source of confusion.
## Run it on the backend
```bash theme={null}
synq-recon run-remote --drill=false --wait
```
The run is asynchronous. `--wait` blocks until it finishes and sets a meaningful exit code; without it, poll with `synq-recon audit-logs get `.
`--invocation-id ` makes submission idempotent — re-submitting with the same id will not start a duplicate run, which is what you want from a retrying pipeline.
**Development → Run** on the suite. The run options dialog carries the same drill and timeout settings.
**Pass `--drill=false` explicitly if you do not want a drill.** Omitting the flag does not mean "off".
Unlike `promote`, where an omitted flag preserves the stored setting, an ad-hoc run has no deployment to inherit from — so an omitted `--drill` falls through to each reconciliation's own `bisection.enabled` in the YAML, which defaults to on. On a suite with genuinely many differences that is the difference between a two-minute run and a fifteen-minute one with nothing usable at the end.
## Promote to production
Promoting creates a **deployment**: an immutable snapshot of the suite plus its schedule, bindings, run settings and annotations.
```bash theme={null}
synq-recon promote \
--schedule "0 */4 * * *" \
--timezone UTC \
--triggerable-by-api \
--drill=false \
--execution-timeout 30m \
--annotation team=data-platform \
--change-summary "Every four hours, no drill"
```
**Promote to production** on the suite card. The dialog covers the schedule and the run settings, and shows a diff of what is about to change against what production is running today.
Once promoted, each reconciliation in the deployment becomes a platform asset that produces a check on every run — so it appears in search and lineage, participates in [check categorisation](/analytics/check-categories), and opens [issues](/incidents/incident-overview) that route through your existing [alerts](/alerts/alert-overview) and [ownership](/ownership/ownership-overview).
### Schedules
Two forms, mutually exclusive:
```bash theme={null}
--schedule "0 */4 * * *" # cron
--ical "FREQ=MONTHLY;BYDAY=TH;BYSETPOS=-1" # RFC 5545 recurrence rule
```
Both take `--timezone` (for example `UTC`, `Europe/Warsaw`); `--ical` additionally accepts `--dtstart` as an anchor. Use iCal for the schedules cron cannot express — last Thursday of the month, the second Tuesday, business-day patterns.
### Two different timeouts
`--timeout` and `--execution-timeout` are unrelated, and mixing them up is easy:
* **`--timeout`** is a **per-query** budget for locally executed commands. Default `5m`.
* **`--execution-timeout`** is the **whole-run** wall-clock budget for a backend run, set on a deployment or per trigger. The server clamps it to its supported range.
## Editing a deployment
Deployment edits **preserve what you omit**. `deployment update` always behaves this way, and so does a re-promote — so refreshing a suite snapshot never silently unschedules the deployment or turns off API triggers.
```bash theme={null}
synq-recon deployment update --execution-timeout 45m # changes only that
synq-recon deployment update --clear # remove the schedule
synq-recon promote --clear-schedule # same, while re-promoting
```
Removing a schedule is therefore always explicit.
**A *fresh* promote applies defaults, and one of them may surprise you.** With no existing deployment to preserve from, a promote defaults to: no schedule, not triggerable by API, the server-default execution timeout — and **drill-down on**.
If you want a scheduled production run that never drills, pass `--drill=false` on the first promote. Do not rely on omission.
**A deployment is a snapshot, not a pointer.** Editing the suite in Development changes nothing in production until you re-promote. The app says so on the suite card — *"Dev has unpromoted changes"* versus *"Up to date with prod"* — and it is worth checking that line before concluding that a fix did not work.
### Keep the deployment id stable
A deployment's id is part of every reconciliation's asset path. Rebuilding a deployment from scratch under a new id re-homes its checks and drops their history.
Re-promoting the same suite reuses its id automatically, so this is only a concern if you are rebuilding deliberately — in which case pin it:
```bash theme={null}
synq-recon promote --deployment-id
```
## Pause, resume, unpromote
```bash theme={null}
synq-recon deployment pause --until 2026-04-01T00:00:00Z
synq-recon deployment pause # indefinitely
synq-recon deployment resume
synq-recon unpromote --reason "Migration complete"
```
Pause is for a planned maintenance window: the deployment stays configured and stops running. Unpromote deactivates it entirely; its history is kept, and re-promoting brings it back under the same id.
`deployment is not active; re-promote to modify` means the deployment was unpromoted. Re-promote before changing or tearing it down.
## Inspecting what ran
```bash theme={null}
synq-recon runs list --status in_progress
synq-recon runs list --trigger scheduled --suite --limit 20
synq-recon runs cancel
synq-recon audit-logs list --status mismatched
synq-recon audit-logs get -o json
synq-recon deployment get -o yaml # schedule, bindings, run settings
synq-recon deployment history # every promote, pause, edit
```
A run's `--trigger` says how it started, which is often the first thing you want to know:
| Trigger | Means |
| ----------- | ------------------------------------------------------------------------------------------------- |
| `adhoc` | Submitted against a Development suite (`run-remote`, or **Run** in the app). |
| `scheduled` | A schedule fired. |
| `api` | An explicit trigger — the Run button on a promoted suite, or an external caller such as a CI job. |
`deployment history` is append-only and records every promote, unpromote, schedule change, binding change, annotation edit, pause and resume. When production behaviour changed and nobody remembers why, it is the first place to look.
## Copy production back to Development
To iterate on what production is actually running, rather than on what Development happens to contain:
```bash theme={null}
synq-recon suite yaml > suite.yaml
# edit
synq-recon upload-config suite.yaml --change-summary "Iterating on the prod snapshot"
```
**Copy production snapshot to development** on the production deployment card.
## Permissions
| Action | Scope |
| ----------------------------------------------------------------------- | --------------------- |
| View suites, deployments, runs, audit logs | `SCOPE_RECON_READ` |
| `upload-config`, suite edits and deletes, ad-hoc runs, cancelling a run | `SCOPE_RECON_EDIT` |
| Promote, unpromote, trigger, pause, resume, deployment edits | `SCOPE_RECON_PROMOTE` |
| Report a locally executed run's results | `SCOPE_RECON_EDIT` |
The app hides controls whose call would be refused, so a missing scope shows up as a missing button rather than an error. [CI/CD and automation](/reconciliation/cicd-and-automation#scopes-and-credentials) maps these to roles and to the credentials an unattended caller uses.
## Next
Reading a run, and following a finding to the rows.
`trigger --wait` as a release gate, exit codes and credentials.