Server CLI

For production deployments, strongly prefer gestaltd lock, then gestaltd sync --locked during image build or release preparation, then gestaltd serve --locked at runtime. The lockfile pins resolved provider artifacts and verified hashes, and locked serve refuses to mutate deployment state.

gestaltd manages server lifecycle and provider releases. For release-backed providers, gestaltd lock writes platform-independent static metadata while sync --locked and locked serve select the runtime archive for the platform where they run.

Server commands

Command	Purpose
`gestaltd`	Local-friendly startup. Generates a config if needed and serves.
`gestaltd serve --config PATH`	Start the server. Repeat `--config` to layer overrides. Local apps with `run:` commands and `apps.<name>.static` are proxied to hot-reload dev servers.
`gestaltd serve --locked --config PATH`	Start read-only from an existing lockfile and prepared artifacts. Repeat `--config` to layer overrides.
`gestaltd serve --artifacts-dir DIR`	Directory for prepared provider artifacts.
`gestaltd serve --lockfile PATH`	Override the lockfile location. `PATH` resolves like a normal CLI path.
`gestaltd lock --config PATH`	Resolve published provider sources and write canonical lock metadata. Repeat `--config` to layer overrides.
`gestaltd lock --check --config PATH`	Verify that the checked-in lockfile matches the current config without rewriting it.
`gestaltd sync --locked --config PATH`	Materialize prepared provider artifacts from an existing lockfile. Local source UI preparation uses bounded parallelism by default.
`gestaltd sync --locked --cache-dir DIR --config PATH`	Reuse materialized prepared artifacts across sync runs. `DIR` resolves like a normal CLI path.
`gestaltd sync --locked --verbose --config PATH`	Emit detailed cache, archive download, timing, and output-size diagnostics while syncing.
`gestaltd sync --locked --output-format=json --config PATH`	Emit one compact JSON metrics document to stdout on successful sync.
`gestaltd sync --locked --check --config PATH`	Verify that prepared artifacts exist and match the lockfile without rewriting them.
`gestaltd validate --config PATH`	Validate config without serving. Repeat `--config` to layer overrides.
`gestaltd validate --lockfile PATH`	Accept the same explicit lockfile path used by `lock`, `sync`, and `serve` without mutating it.
`gestaltd --version`	Print the server version.

Provider commands

Command	Purpose
`gestaltd provider search [QUERY]`	Search configured provider repositories. Pass `--repo NAME` to search one repository.
`gestaltd provider info PACKAGE`	Show available versions and release metadata for one package. Pass `--repo NAME` to disambiguate.
`gestaltd provider add PACKAGE --config PATH`	Add an indexed provider package to config and update the lockfile. Package sources are written by default.
`gestaltd provider add PACKAGE --kind KIND --name NAME`	Choose the provider kind and config entry name explicitly.
`gestaltd provider add PACKAGE --version CONSTRAINT`	Write a semver version constraint such as `^1.4.0`, `~1.4.0`, or an exact version.
`gestaltd provider add PACKAGE --exact-source`	Write the resolved `provider-release.yaml` URL instead of a package source.
`gestaltd provider add PACKAGE --sync`	Materialize prepared artifacts after locking.
`gestaltd provider list --config PATH`	List configured providers and lock status. Pass `--kind KIND` to filter.
`gestaltd provider remove NAME --config PATH`	Remove one provider entry and update the lockfile. Pass `--kind KIND` when the name is ambiguous.
`gestaltd provider upgrade --config PATH`	Refresh lock state for all package sources without editing config version constraints.
`gestaltd provider upgrade NAME --version CONSTRAINT`	Change one package source’s version constraint and update the lockfile.
`gestaltd provider repo add NAME URL`	Add a provider repository to the user-level store. Pass `--config PATH` to write `providerRepositories` into project config instead.
`gestaltd provider repo list`	List the default, user-level, and project provider repositories.
`gestaltd provider repo update`	Fetch and cache provider repository indexes.
`gestaltd provider repo remove NAME`	Remove a provider repository from the user-level store. Pass `--config PATH` to remove it from project config instead.
`gestaltd serve [PATH]...`	Run one or more local source apps. Without `--config`, serves a synthesized baseline (unlocked).
`gestaltd serve [PATH]... --config PATH`	Layer local-source PATH overrides on top of the user config. Repeat `[PATH]...` and `--config` as needed. With `--locked`, the fleet loads pinned artifacts while PATH apps with `run:` commands hot-reload from local trees.
`gestaltd provider validate --path PATH`	Validate a local source app inside the same synthesized Gestalt config used by `gestaltd serve [PATH]...`.
`gestaltd provider validate --config PATH`	Validate the target provider together with selected supporting providers and `null` deletions from layered config overlays.
`gestaltd provider package --version VERSION`	Build provider release archives from a source directory. Executable source providers use SDK-native source packages or `build` phases and default to the host platform; declarative providers default to a generic archive. Pass `--platform ...` with `os/arch` targets or `--platform all` for multi-platform builds.
`gestaltd provider package --output DIR`	Output directory for the release archives. Defaults to `dist/`.
`gestaltd provider release --dist-dir DIR`	Finalize already-built release archives by validating them and writing `provider-release.yaml` into the dist directory.

For config-free local development, inferred static mount paths use the manifest source slug rather than the API-safe provider key. A source ending in workspace-review mounts at /workspace-review when apps.<name>.static.mount is omitted. Explicit apps.<name>.static.mount values take precedence.

Provider package commands use the provider repository model described in Provider packages. Mutating package commands accept one --config path so the CLI edits the intended file instead of a merged runtime view. provider add, provider remove, and provider upgrade NAME --version update the lockfile by default. provider add and provider remove accept --no-lock when you need to edit config only.

gestaltd sync --locked --parallelism N caps concurrent preparation for local source.path app builds. The default is up to four workers, capped by GOMAXPROCS; --parallelism 1 forces sequential preparation. Other provider types and sync --locked --check remain sequential.

gestaltd sync --locked --cache-dir DIR enables an opt-in cache for materialized prepared artifacts. The cache key is the locked archive identity, including the archive SHA-256, resolved archive key, platform, and materializer version. Cache hits restore prepared outputs directly; misses download and install the package, then populate the cache after a successful install. sync --locked --check remains read-only and does not populate the cache. Treat this cache as trusted deployment state: only principals that are allowed to influence deployed prepared artifacts should be able to write to it.

gestaltd sync --locked -v and gestaltd sync --locked --verbose add human-readable diagnostics for cache behavior, archive downloads, phase timings, prepared output size, and archive fetches. There is one verbosity level; -vv is not supported. The top-level gestaltd -v still prints the server version. Without -v or --output-format=json, successful gestaltd sync --locked remains quiet.

gestaltd sync --locked --output-format=json writes one compact JSON metrics document to stdout on success. Child source-build output and errors go to stderr so CI can redirect stdout to a JSON file safely. On failure, stdout is empty and the error is written to stderr. --output-format defaults to text; supported values are text and json.


gestaltd sync \
  --locked \
  --config ./deploy/config.yaml \
  --artifacts-dir ./deploy
 
gestaltd sync \
  --locked \
  --verbose \
  --config ./deploy/config.yaml \
  --artifacts-dir ./deploy \
  --cache-dir ./.gestaltd-cache
 
gestaltd sync \
  --locked \
  --output-format=json \
  --config ./deploy/config.yaml \
  --artifacts-dir ./deploy \
  > gestaltd-sync.json
 
gestaltd sync \
  --locked \
  --verbose \
  --output-format=json \
  --config ./deploy/config.yaml \
  --artifacts-dir ./deploy \
  --cache-dir ./.gestaltd-cache \
  > gestaltd-sync.json

The JSON schema version is 2 and reports the sync action, inputs, artifact count and decisions, materialized cache counters, archive download counters, archive fetches, phase timings, and prepared output size. In --check mode, the action is check, cache writes remain zero, and output.measured is false.

JSON field	Meaning
`schema.version`	Metrics schema version. Current version is `2`.
`sync.action`	`materialize` for normal sync or `check` for `--check`.
`sync.duration_seconds`	Total successful sync duration.
`inputs.config_paths`	Config files passed to sync after CLI path resolution.
`artifacts.considered`	Prepared artifact entries in the effective config.
`artifacts.items`	All prepared artifact decisions recorded by the run, sorted by duration descending.
`cache.configured`	Whether `--cache-dir` was passed.
`cache.enabled`	Whether this sync mode can read and write the materialized cache.
`cache.dir`	Resolved cache directory.
`cache.mode`	Cache mode. Currently `materialized`.
`cache.bucket_version`	Cache bucket version. Currently `materialized/v1`.
`cache.hits`, `cache.misses`, `cache.invalid`	Materialized cache lookup counters.
`cache.prefetch.*`	Sparse remote-cache prefetch counters: duration, requests, eligible requests, unique keys, local hits, remote hits, remote misses, failures, and bytes read.
`cache.put.successes`, `cache.put.failures`	Materialized cache write counters. Write failures do not fail sync.
`cache.entries`	Cache events recorded by the run.
`archives.requests`	Current-platform archive acquisition attempts made by this run.
`archives.unique_sha256`	Unique canonical expected SHA-256 values among archive requests.
`archives.downloads.*`	Successful remote archive download count, bytes, and cumulative download time.
`archives.fetches`	All archive acquisitions recorded by the run, sorted by duration descending.
`phases.*_seconds`	Major lifecycle phase timings. Download time is cumulative and may not sum to wall-clock time under parallelism.
`output.files`, `output.bytes`	Aggregate prepared output measurement over known prepared artifact roots, not the entire artifacts directory.
`output.roots`	All measured prepared output roots, sorted by bytes descending.

Local Frontend Development

When an app manifest declares run: commands and deployment config sets apps.<name>.static, gestaltd serve spawns the declared commands and reverse-proxies the mount path to the process that binds GESTALT_DEV_PORT. Framework hot reload works through the proxy, including websocket traffic.


run:
  - command: [npm, run, dev]
    readyTimeout: 120s

gestaltd injects (after manifest env entries):

Variable	Purpose
`GESTALT_DEV`	Set to `1`
`GESTALT_DEV_PORT`	Port the frontend dev server must bind on `127.0.0.1`
`GESTALT_DEV_BASE_PATH`	Mount path from `apps.<name>.static.mount`
`GESTALT_BASE_URL`	Public gestaltd origin for two-origin Vite `/api/v1` proxying
`GESTALT_PROVIDER_SOCKET`	Unix socket for the app provider when a backend `run` command is present

Map these in your framework dev script. See Applications > Local Development for Vite, Angular, webpack-dev-server, and Parcel examples.

Production and gestaltd serve --locked serve prepared static/ artifacts, except for apps passed as positional PATH arguments with active run: commands — those are dev-proxied even under --locked. Config or provider changes require restarting gestaltd.

For faster iteration on a local frontend while the rest of the fleet runs from pinned artifacts, pass PATH arguments together with --config and --locked:


gestaltd serve --locked \
  --config ./deploy/config.yaml \
  --config ./deploy/local/config.yaml \
  ./apps/g-issues/ui \
  ./apps/delta/ui

For a standalone local provider without the full fleet config, pass PATH to gestaltd serve for a source tree or layer a small local config that includes only the app under test:


gestaltd serve \
  --config ./config.yaml \
  --config ./support-local.yaml

Examples


gestaltd
gestaltd lock --config ./config.yaml
gestaltd sync --locked --config ./config.yaml
gestaltd sync --locked --config ./config.yaml --cache-dir ./.gestaltd-cache
gestaltd sync --locked --config ./config.yaml --verbose
gestaltd sync --locked --config ./config.yaml --output-format=json > gestaltd-sync.json
gestaltd sync --locked --config ./config.yaml --parallelism 2
gestaltd serve --locked --config ./config.yaml
gestaltd validate --config ./config.yaml
gestaltd lock --config ./config.yaml --lockfile ./local/gestalt.lock.json
gestaltd sync --locked --config ./config.yaml --lockfile ./local/gestalt.lock.json
gestaltd serve --config ./config.yaml --lockfile ./local/gestalt.lock.json
gestaltd serve ./apps/support/manifest.yaml
gestaltd serve --locked --config ./config.yaml ./apps/workspace-review
gestaltd serve --locked --config ./config.yaml --lockfile ./local/gestalt.lock.json
gestaltd lock --config ./base.yaml --config ./overrides/prod.yaml
gestaltd sync --locked --config ./base.yaml --config ./overrides/prod.yaml
gestaltd serve --locked --config ./base.yaml --config ./overrides/prod.yaml
gestaltd provider search github
gestaltd provider info github.com/valon-technologies/gestalt-providers/app/github
gestaltd provider repo list
gestaltd provider repo add gestalt https://registry.gestaltd.ai/provider-index.yaml --config ./config.yaml
gestaltd provider repo update --config ./config.yaml
gestaltd provider add github.com/valon-technologies/gestalt-providers/app/github --config ./config.yaml --name github
gestaltd provider add github.com/valon-technologies/gestalt-providers/auth/oidc --config ./config.yaml --kind identity --name oidc --version '^1.4.0'
gestaltd provider list --config ./config.yaml
gestaltd provider list --config ./config.yaml --kind app
gestaltd provider upgrade --config ./config.yaml
gestaltd provider upgrade github --config ./config.yaml --kind app --version '^1.5.0'
gestaltd provider remove github --config ./config.yaml --kind app
gestaltd provider validate --path ./apps/support
gestaltd provider validate --path ./apps/support --config ./dev/support.yaml --config ./dev/local.yaml
gestaltd serve ./apps/support
gestaltd serve ./apps/support --config ./dev/support.yaml
gestaltd serve ./apps/support --config ./dev/support.yaml --port 8080
gestaltd serve --locked --config ./config.yaml ./apps/workspace-review ./apps/delta
gestaltd provider package --version 0.0.1-alpha.1
gestaltd provider package --version 0.0.1-alpha.1 --platform all
gestaltd provider package --version 0.0.1-alpha.1 --platform linux/amd64,linux/arm64
gestaltd provider release --dist-dir dist --version 0.0.1-alpha.1

When repeated, --config files merge left-to-right. Maps deep-merge, later scalar values win, lists replace inherited lists, and null deletes inherited keys. By default, lockfiles and artifact paths use the current working directory. --lockfile overrides only the lockfile path. --artifacts-dir overrides only the artifacts directory path.

For source-backed providers, gestaltd serve [PATH]... starts the manifest run argv when one is declared. If run is omitted, it serves or starts the declared entrypoint or SDK-native source package. Sequence-form build commands can prepare dependencies before local startup; output-producing build.command remains the packaging path for compiled artifacts.

See Configuration for the relationship between lock, sync --locked, serve --locked, and validate.