CLI reference

Run a Synthigy instance, or connect your code to one

Client — connect developers, services and bots to a Synthigy server

synthigy connect

Authenticate against a Synthigy server and save the connection to this profile

synthigy connect <server-url> [flags]

Examples:

  synthigy connect http://localhost:7887
  synthigy connect https://server.example.com --insecure
  synthigy connect https://server.example.com --client-id svc --client-secret "$SECRET"
  synthigy --env .synthigy/customer2.env connect https://customer2.example.com

Flags:

      --client-id string       Connect as a service: this client's id (non-interactive)
      --client-secret string   Connect as a service: this client's secret (or set SYNTHIGY_CLIENT_SECRET)
      --insecure               Skip TLS certificate verification
      --user                   Force the device-flow (browser) login, skipping the interactive prompt
  -v, --verbose                Verbose output

synthigy disconnect

Disconnect from server and revoke tokens

synthigy disconnect

Examples:

  synthigy disconnect
  synthigy --env .synthigy/customer2.env disconnect

synthigy exec

Run a command under an instance's env (discovered, or explicit -f profiles)

synthigy exec [-f FILE...] -- COMMAND [ARGS...] [flags]

Flags:

  -f, --env-file stringArray   env file to load instead of discovery (repeatable; later files win)
      --show                   print the merged keys to stderr before running (secrets masked)

synthigy schema

The schema snapshot XSQL editor tooling reads

synthigy schema

synthigy schema check

Fail when

/schema.json is older than the deployed model

synthigy schema check [flags]

Examples:

  synthigy schema check
  synthigy schema check --dir queries

Flags:

      --dir string   Directory holding .xsql sources and schema.json (default "xsql")

synthigy schema pull

Refresh

/schema.json from the connected instance

synthigy schema pull [flags]

Examples:

  synthigy schema pull
  synthigy schema pull --dir queries
  synthigy schema pull --role Editor --role Viewer
  synthigy --env .synthigy/customer2.env schema pull

Flags:

      --dir string         Directory holding .xsql sources; schema.json is written here (default "xsql")
      --role stringArray   project the schema onto this role (repeatable)

synthigy token

Print a fresh access token for this profile's saved identity

synthigy token

Examples:

  synthigy token
  synthigy --env .synthigy/customer2.env token

synthigy whoami

Show current user information

synthigy whoami

Examples:

  synthigy whoami
  synthigy --env .synthigy/customer2.env whoami

Server — run and operate a Synthigy instance here

synthigy clean

Prune cached releases and old JREs from ~/.synthigy

synthigy clean [flags]

Flags:

      --keep int   Number of most recent releases to keep (default 2)

synthigy console

Open the portal: setup, health and configuration of the instance on this machine

synthigy console [flags]

Flags:

  -p, --print   Print the URL only, don't open a browser

synthigy down

Stop the engine and the portal started by 'up'

synthigy down

synthigy iam

Export, import and script IAM configuration

synthigy iam

synthigy iam add-client

Create an OAuth client (and its service user), scripted

synthigy iam add-client <name> [flags]

Flags:

      --api stringArray        audience this client may request a token for (repeatable, confidential only)
      --grant stringArray      allowed grant type, e.g. client_credentials (repeatable)
      --id string              client id (default: server-generated)
      --local                  go through the portal of the instance on this machine instead of a connected server
      --redirect stringArray   allowed redirect URI for authorization_code (repeatable)
      --role stringArray       grant this role to the service user (repeatable, confidential only)
      --secret string          pin the client secret instead of generating one; on an existing client this is the only way to change it
      --trusted                mark the client trusted: no consent screen, and it may run requests as its users (acting_as)
      --type string            public or confidential (default "public")

synthigy iam export

Export IAM configuration as JSON to stdout

synthigy iam export <type> [name...] [flags]

Flags:

      --id stringArray   export only the record with this id (repeatable; only OAuth clients have one)

synthigy iam import

Import IAM configuration from a JSON file

synthigy iam import <type> <file> [flags]

Flags:

      --dry-run       validate without writing
      --mode string   sync (declarative) or stack (additive) (default "sync")

synthigy iam remove-client

Delete an OAuth client and its service user

synthigy iam remove-client <id>

synthigy logs

Show this instance's engine process log (boot and crash output)

synthigy logs [flags]

Examples:

  synthigy logs
  synthigy logs -f
  synthigy logs -n 500

Flags:

  -f, --follow      Keep printing as the log grows
  -n, --lines int   Number of trailing lines to print (default 200)

synthigy pull

Download a release's bundle into the cache without starting anything

synthigy pull [flags]

Examples:

  synthigy pull --bundle postgres
  synthigy pull --bundle sqlite --version v0.2.12

Flags:

      --bundle string    Bundle: sqlite | postgres | postgres-clickhouse (default "sqlite")
      --version string   Release version (e.g. v0.2.12) (default "latest")

synthigy service

Run this instance as a boot-time service (systemd user unit / launchd agent)

synthigy service

synthigy service install

Install and enable the service for the current instance home

synthigy service install

synthigy service status

Show the service's state

synthigy service status

synthigy service uninstall

Stop, disable and remove the service (the instance data is untouched)

synthigy service uninstall

synthigy up

Start the Synthigy engine (cold start: provisions JRE, launches the JVM)

synthigy up [flags]

Examples:

  synthigy up                                # opens the setup wizard on a fresh install
  synthigy up --bundle postgres              # needs POSTGRES_* env; persists the choice
  synthigy up --version v0.2.12              # pin a release
  synthigy up --jar synthigy.jar             # local/airgap jar, no download
  synthigy up --join                         # stay attached (systemd / launchd / container PID 1)
  synthigy --env .synthigy/customer1.env up  # replaces <instance-home>/.env, for running several instances

Flags:

      --bundle string    Bundle: sqlite | postgres | postgres-clickhouse — write-through to .env; missing and unset opens the wizard
      --force            Re-download every module even if cached (suspected corruption)
      --jar string       Local jar, or a classpath of module jars, instead of a release download; airgap/custom builds
      --join             Stay attached to this terminal instead of detaching — for process supervisors (systemd Type=simple, launchd, a container's PID 1), which need the process they started to keep running
      --version string   Release version to run (e.g. v0.2.12) (default "latest")

synthigy versions

List available Synthigy releases

synthigy versions

Common

synthigy completion

Generate the autocompletion script for the specified shell

synthigy completion

synthigy doctor

Run system health checks

synthigy doctor

synthigy env

Manage this project's local Synthigy instance (.synthigy/.env)

synthigy env

synthigy env init

Scaffold ./.synthigy for a project-local instance

synthigy env init

synthigy status

Show this instance and its saved connection, offline

synthigy status

Examples:

  synthigy status
  synthigy --env .synthigy/customer2.env status

synthigy upgrade

Upgrade (or downgrade) the synthigy CLI binary

synthigy upgrade [flags]

Examples:

  synthigy upgrade
  synthigy upgrade --version v0.1.9   # pin an older CLI

Flags:

      --version string   CLI release tag to install (e.g. v0.1.10) (default "latest")

synthigy version

Print version information

synthigy version

Global flags

      --env string   Profile file to use instead of <instance-home>/.env (default: $SYNTHIGY_ENV_FILE)
  -v, --verbose      Verbose output