Use the synsmarts CLI

The synsmarts command is installed in each App’s managed SSH shell. The shell injects an App-bound API key and API endpoint. The Team and App are still explicit resource addresses: set SYNSMARTS_TEAM and SYNSMARTS_APP, or pass --team and --app. The key authorizes access to that addressed App; it doesn’t select the App.

Run:

synsmarts --help
synsmarts <command> --help

The managed shell exposes deploy, maintenance, and restore. A local installation of the full CLI also exposes waf.

Use common options

Each command group accepts these options before its subcommand:

Option	Purpose
--api-key <key>	Override the configured API key. Avoid this in shell history.
--api-url <url>	Override the API base URL.
--team <team>	Address a Team by slug or UUID.
--app <app>	Address an App by slug or UUID.
-v, --verbose	Write HTTP request status and trace identifiers to stderr.
--json	Write machine-readable output to stdout.

For a local installation or automation runner, configure the environment or ~/.synsmarts/config.yaml. See CLI configuration file.

Deploy

List and inspect releases:

synsmarts deploy list
synsmarts deploy list --env <environment>
synsmarts deploy status <deploy-id>

Deploy an exact Git revision:

synsmarts deploy trigger \
  --env <active-environment> \
  --source-type git \
  --source-ref <commit-sha>

Deploy the current server-side Workspace:

synsmarts deploy trigger --env <active-environment> --source-type workspace

--env is required by the current CLI request shape, but it doesn’t select among multiple environments. The deploy API targets the App’s sole active environment and reports that canonical environment name in the result.

The command waits for a terminal result by default. A dispatch acknowledgement or intermediate phase isn’t proof that the release is live.

Use --no-wait to return after dispatch, --max-wait <seconds> to change the 1800-second wait limit, or --no-tui for one greppable progress line per phase.

If the App has a connected repository, the Workspace deploy doesn’t commit files to Git or change automatic-deploy settings. A later Git deploy can replace code that exists only in the Workspace. See Git and Workspace deploys.

Roll back a deploy after reviewing its data impact:

synsmarts deploy rollback <deploy-id>
synsmarts deploy rollback <deploy-id> --no-wait
synsmarts deploy rollback <deploy-id> --max-wait 1800

Rollback waits for the new rollback deploy by default. --no-wait returns after dispatch; --max-wait <seconds> bounds polling. See Roll back a deploy before submitting it.

Reapply committed configuration

Use an admin-scope API key to reapply the App’s committed configuration without changing its contents:

synsmarts deploy config-reconcile <app-id> --yes

The command returns without a deployment when the recorded applied projection already matches the committed configuration. Use --force when the running services don’t match that committed state even though the projection is current:

synsmarts deploy config-reconcile <app-id> --force --yes

A forced reapply validates the committed file and starts a configuration deploy. --yes confirms that every setting in the committed file may be re-applied. Save the returned deployment ID and inspect it with synsmarts deploy status <deploy-id>. The managed shell’s injected deploy credential doesn’t grant this admin operation; configure an admin-scope key for the CLI before running it.

Manage maintenance mode

Review or change the current state:

synsmarts maintenance status
synsmarts maintenance enable
synsmarts maintenance disable

This surface operates on production only. Omit --env, or pass --env production; any other value is rejected.

Manage page content in a local directory from a full CLI installation with PyYAML. The managed-shell bundle supports maintenance status, enable, and disable, but doesn’t include the PyYAML dependency required by page pull, preview, and push:

synsmarts maintenance page pull --dir ./maintenance
synsmarts maintenance page preview \
  --dir ./maintenance \
  --output ./maintenance-preview.html
synsmarts maintenance page push --dir ./maintenance

The directory can contain page.html, page.css, page.yaml, and assets/. Preview runs the same server-side validation as push. Push waits for the configuration apply unless --no-wait is set. Use --max-wait <seconds> to change the 1800-second push wait limit.

See Manage maintenance mode for content and asset limits.

Restore data

Restore commands require Team and App identifiers or slugs. Pass --team and --app, set SYNSMARTS_TEAM and SYNSMARTS_APP, or configure team and app in a full local CLI installation. In the managed shell, pass both resource segments because the bundled CLI can’t read the YAML configuration file and the shell doesn’t set them.

Review restore history:

synsmarts restore --app <app> list
synsmarts restore --app <app> list --status running
synsmarts restore --app <app> status <restore-id>

The restore status filter accepts pending, running, needs_operator, completed, completed_with_errors, failed, and dispatch_failed.

Start a point-in-time database restore:

synsmarts restore --app <app> db \
  --at 2026-07-25T18:30:00Z \
  --wait

Restore a named database backup:

synsmarts restore --app <app> db \
  --backup <backup-name> \
  --wait

Restore all app files from a snapshot:

synsmarts restore --app <app> files \
  --snapshot <snapshot-id> \
  --wait

Caution

This replaces every file in the app’s files volume and takes the site down briefly while it swaps. Your database and media aren’t touched, and there is no partial or per-file option. A safety snapshot of the current files is taken automatically first.

The command asks you to type the app slug to confirm; pass --yes to skip that in a script.

Restore one media object to its version at a timestamp:

synsmarts restore --app <app> media \
  --object-key <media-object-key> \
  --at 2026-07-25T18:30:00Z \
  --wait

Restore dispatch is non-blocking by default. Without --wait, a successful command returns after the restore is accepted and prints its identifier; use status to follow the server-side operation.

Database restore is destructive and uses a typed confirmation. Media restore replaces the current object but retains its prior version within the recovery window. Non-interactive use must pass --yes; use it only after an independent review of the exact target.

Only one restore can run for an App at a time. A conflicting dispatch is rejected; check restore list and restore status before retrying.

--wait uses a 3600-second default limit. A timeout detaches from the operation; it doesn’t cancel the server-side restore.

See Restore a database and Restore media.

Manage the WAF

Run WAF commands from a local installation or automation runner. The managed shell front-end doesn’t expose the waf command.

Show the current policy and recent events:

synsmarts waf get
synsmarts waf events
synsmarts waf events --cursor <cursor>
synsmarts waf events --all --max-pages 10

Without --all, text mode prints the next opaque cursor to stderr when more events exist. With --json, read next_cursor from stdout. Pass the value back with --cursor to continue from that page.

Patch supported fields:

synsmarts waf set --mode block --paranoia-level 2

The mode values are off, detect, and block. Protection level accepts 1 through 4: 1 Basic, 2 Standard, 3 Very strict, 4 Maximum. Standard is the recommended level for a store handling customer data or payments.

Path exclusions, path rules, and geographic rules are structured lists rather than single values, so they are set with --file (below) or in the portal.

Replace the complete WAF block from YAML or JSON:

synsmarts waf set --file ./waf.yaml

Don’t combine --file with field flags. Field flags patch the current policy; --file replaces the full block.

See Configure the WAF.

Use the CLI in automation

• Prefer an exact Git commit SHA over a branch or tag.
• Use --json and parse stdout; progress and diagnostics are written to stderr.
• Set a bounded wait and record the returned deploy or restore identifier.
• Treat a wait timeout as an unknown final state and query status before retrying.
• Never print, commit, or pass an API key as a visible command argument when an environment variable or protected configuration file is available.
• Don’t submit duplicate destructive operations after a network interruption; check the operation list and status first.

Exit codes

Most deploy and maintenance failures exit 1. Invoking those groups without a subcommand also prints help and exits 1; argparse validation errors and an unknown top-level command exit 2. Restore commands provide these additional stable outcomes:

Code	Restore outcome
0	Dispatch accepted, or a waited restore completed successfully.
1	Validation, dispatch, or restore failed.
2	The wait limit elapsed while the restore remained non-terminal.
130	Waiting was interrupted; the server-side restore continues.

WAF commands use standard sysexits codes so automation can distinguish the failure class:

Code	WAF outcome
0	Success
1	Unclassified client failure or unexpected local error.
65	Submitted policy, revision, or file data was rejected.
66	The --file path couldn’t be read.
69	The API was unavailable or unreachable.
70	The API returned an unexpected server error.
75	The change was stale or another change is in progress.
77	The API rejected the key as invalid or insufficient.
78	Local configuration is invalid or incomplete, including no configured API key.

WAF argparse usage errors exit 2.