How-to guide

Use the synsmarts CLI

The synsmarts command is installed in each App’s managed SSH shell. The shell injects an App-bound API key, the API endpoint, and the App’s Team and App as SYNSMARTS_TEAM and SYNSMARTS_APP, so commands there need no setup. Elsewhere, set those variables or pass --team and --app. The key authorizes access to the addressed App; it doesn’t select the App.

Run:

synsmarts --help
synsmarts commands
synsmarts <command> --help
synsmarts --version

Every published API operation has a command, and synsmarts commands lists them all: deploys, configuration, diagnostics and logs, live service status, service actions, recommendations, backups, DNS, billing, and support tickets. A command’s flags are the operation’s parameters in the API reference. maintenance, restore, and waf keep their own options, described below.

Use common options

Every command accepts these options before or after 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 the API’s JSON response body 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.

A deploy needs confirmation. On a terminal, the command asks you to type yes; in a script, pass --yes.

The command returns after dispatch and prints the deploy identifier. A dispatch acknowledgement isn’t proof that the release is live: add --wait to wait for a terminal result, or --follow to wait and print one greppable progress line per phase. --timeout <seconds> changes the 1800-second wait limit.

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> --yes
synsmarts deploy rollback <deploy-id> --yes --wait
synsmarts deploy rollback <deploy-id> --yes --wait --timeout 1800

Rollback returns after dispatch. --wait waits for the new rollback deploy to finish; --timeout <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. The managed shell sets SYNSMARTS_TEAM and SYNSMARTS_APP; elsewhere, pass --team and --app, set those variables, or configure team and app in a full local CLI installation.

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

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.

On a MariaDB App, restore db restores whole backups only; a point-in-time request fails with RESTORE_ENGINE_UNSUPPORTED.

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 the managed shell, a local installation, or an automation runner. waf set --file with YAML needs a full local installation with PyYAML.

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

Commands generated from the API, deploy among them, use these codes:

Code	Outcome
`0`	The request succeeded, or a waited operation finished or awaits approval.
`1`	A waited operation failed, or the API couldn’t be reached.
`2`	The wait limit elapsed before the operation finished.
`3`	The API refused the request; stderr carries its `error_code`.
`4`	Usage error: unknown command or flag, or no API key, Team, or App.
`130`	Waiting was interrupted; the server-side operation continues.

With --json, a generated command that fails writes one JSON object as the last line of stderr. It always has title and detail. An API refusal adds the problem’s status, error_code and trace_id, plus retry_after on 429. A waited operation that fails or times out adds operation_id and state, and keeps its last record on stdout. --verbose lines come before the object.

if ! synsmarts deploy --json list 2>err.log >deploys.json; then
  tail -n 1 err.log | jq -r '.error_code // .title'
fi

Maintenance failures exit 1. Restore commands provide these 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.