Date: January 2025 Status: Design Phase
This document is the authoritative reference for Scind's command-line interface. It defines command structure, arguments, flags, and behaviors.
Scind follows a resource-first pattern inspired by Docker and Mutagen:
scind [resource] [action] [options...]
All targeting uses options rather than positional arguments:
# Good: Options-based
scind app status --workspace=dev --app=frontend
# With context detection (from current directory)
scind app statusScind automatically detects workspace and application context from the current directory, reducing the need for explicit --workspace and --app flags.
Context detection uses a workspace boundary approach to prevent accidental detection of config files in vendor packages or nested test fixtures.
-
Workspace context (found first): Walk up the directory tree looking for
workspace.yaml- If found, this establishes the workspace root
- The
workspace.namevalue becomes the implicit--workspacevalue
-
Application context (bounded by workspace): Walk up from current directory toward the workspace root looking for
application.yaml- Only considers
application.yamlfiles within the workspace directory tree - If found, the directory name containing it becomes the implicit
--appvalue - Never traverses above the workspace root—this prevents vendor packages from hijacking context
- Only considers
-
Both can be detected simultaneously:
~/workspaces/dev/frontend/src/components/ │ │ │ └── application.yaml → app = "frontend" │ └── workspace.yaml → workspace = "dev" -
Explicit flags override detection:
--workspaceand--appalways take precedence over context detection- When any
--appflag is specified, context-detected application is completely ignored - This applies even when multiple
-aflags are used - To start multiple specific apps:
scind up -a frontend -a backend
- When any
-
Global commands ignore context:
port,proxy, andconfigcommands don't use directory context
When explicit flags are provided, they replace (not add to) context detection:
# From within frontend directory (context would detect frontend)
$ cd ~/workspaces/dev/frontend
# This starts ONLY backend, not both frontend and backend
$ scind up -a backend
# Starting: backend
# (frontend from context is ignored)
# To start multiple apps, list them all explicitly
$ scind up -a frontend -a backend
# Starting: frontend, backendThis "explicit replaces context" behavior ensures predictable results—when you specify apps explicitly, you get exactly what you asked for.
Nested vendor packages: If working in frontend/vendor/some-package/ where the vendor package has its own application.yaml, it is ignored. The workspace's frontend/application.yaml is found first when walking toward the workspace root.
Workspace within workspace: If a test fixture has its own workspace.yaml nested inside a workspace (e.g., for integration tests), the closest workspace.yaml wins—this is the test fixture, which is the expected behavior.
When context is detected, commands indicate what was found:
$ cd ~/workspaces/dev/frontend
$ scind app status
# Using workspace: dev (from ../workspace.yaml)
# Using app: frontend (from ./application.yaml)
Status: running
Services: 3 running, 0 stopped
...Use --quiet or -q to suppress context indicators.
When context is required but not detected, error messages provide debugging hints:
No workspace found, but application.yaml exists (helps identify misplaced apps):
$ cd ~/random-project
$ scind app status
Error: No workspace found (workspace.yaml) in current directory or any parent directories,
but found an application (application.yaml) at: /home/user/random-project/application.yaml
Create a workspace with: scind workspace init --workspace=NAMENeither workspace nor application found:
$ cd ~
$ scind app status
Error: No workspace found (workspace.yaml) in current directory or any parent directories,
and no application (application.yaml) found either.
Either:
1. Run from within a workspace directory
2. Specify explicitly: scind app status --workspace=NAME --app=NAME
Available workspaces: scind workspace listWorkspace found but no application context (for app-specific commands):
$ cd ~/workspaces/dev
$ scind app status
Error: No application context detected.
Either:
1. Run from within an application directory
2. Specify explicitly: scind app status --app=NAME
Available apps in 'dev': frontend, backend, shared-dbScind manages these resource types:
| Resource | Description | Context-Aware |
|---|---|---|
workspace |
Isolated environment containing applications | Yes |
app |
A Docker Compose application within a workspace | Yes |
flavor |
Named configuration for running an application | Yes |
port |
Host port assignments for assigned-type services | No |
proxy |
The Traefik reverse proxy layer | No |
config |
Global and user configuration | No |
These flags are available on all commands:
| Flag | Short | Description |
|---|---|---|
--workspace |
-w |
Specify workspace (overrides context detection) |
--app |
-a |
Specify application (overrides context detection) |
--quiet |
-q |
Minimal output, suppress context indicators and progress |
--verbose |
-v |
Detailed output |
--json |
Output in JSON format | |
--yaml |
Output in YAML format | |
--color |
Color output: auto (default), always, or never |
|
--help |
-h |
Show help for command |
--version |
Show Scind version |
Both scind --version and scind version display version information. The --version flag is available on all commands.
$ scind --version
scind version 0.2.3
$ scind version
scind version 0.2.3Build provenance: Release builds append SemVer build metadata to the version string so bug reports identify exactly what is running, regardless of install channel:
$ scind --version
scind version 0.2.3+brew.a1b9c3f.clean.20250114The suffix follows the SemVer + build-metadata grammar, with dot-separated fields in a fixed order:
| Field | Meaning | Example |
|---|---|---|
| source | Install channel the binary came from | brew, deb, go-install, source |
| rev | Short git revision the build was cut from | a1b9c3f |
| dirty | Working-tree state at build time | clean or dirty |
| date | Build date, YYYYMMDD (UTC) |
20250114 |
Fields are populated at build time and are informational only—because SemVer ignores build metadata when ordering versions, they never affect version comparison. Development builds without injected metadata fall back to a bare version (optionally +source.unknown). Credit to the Xcind proof-of-concept, which established the +source.rev.dirty.date shape for cross-channel bug triage.
Progress output: Multi-application operations show per-application progress by default:
Starting frontend... done
Starting backend... done
Starting shared-db... done
--quiet behavior:
- Suppresses context indicators ("Using workspace: dev")
- Suppresses progress messages ("Starting frontend... done")
- Status commands output just the value:
running - List commands output names only, one per line
- Errors are always shown regardless of
--quiet
# Normal output
$ scind workspace list
NAME APPS STATUS PATH
dev 3 running ~/workspaces/dev
staging 2 stopped ~/workspaces/staging
# Quiet output (machine-readable)
$ scind workspace list -q
dev
staging
# Status with quiet
$ scind app status -q
runningManage workspace lifecycle and orchestration.
List all registered workspaces.
scind workspace list [flags]Flags:
| Flag | Description |
|---|---|
--validate |
Check that registered paths still contain workspace.yaml |
--rebuild |
Rebuild registry from Docker labels (useful if registry is missing) |
Output (default table):
NAME APPS STATUS PATH
dev 3 running ~/workspaces/dev
review 3 stopped ~/workspaces/review
control 2 running ~/workspaces/control
Discovery mechanism: Reads from the workspace registry (~/.config/scind/workspaces.yaml). If the registry is missing, automatically attempts to rebuild from Docker container labels.
Remove stale entries from the workspace registry.
scind workspace prune [flags]Flags:
| Flag | Description |
|---|---|
--dry-run |
Show what would be removed without making changes |
Behavior:
- Checks each registered workspace path for a valid
workspace.yaml - Removes entries where the path no longer exists or lacks a valid config
- Reports removed entries
Example:
scind workspace prune
# Removed: old-project (path /home/user/old-project no longer exists)
# Registry: 3 workspaces remainingAdd an existing workspace directory to the registry without re-running init.
scind workspace register <path>Arguments:
| Argument | Description |
|---|---|
path |
Path to a directory containing a workspace.yaml |
Behavior:
- Reads
workspace.namefrom theworkspace.yamlatpathand adds aname → pathentry to the registry (~/.config/scind/workspaces.yaml) - Intended for a workspace that was cloned but never run, so it carries no Docker labels yet and would not be recoverable by a label-based
--rebuild - Does not generate overrides, create networks, or start anything—registration is a pure registry write
- Fails if the name is already registered to a different path (same uniqueness rule as
init)
Example:
git clone git@github.com:org/dev-workspace.git ~/workspaces/dev
scind workspace register ~/workspaces/dev
# Registered "dev" -> ~/workspaces/devThis complements workspace init (which both scaffolds and registers): use register when the directory already exists. See State Management for the registry format. Credit to the Xcind proof-of-concept for fine-grained registry operations.
Remove a single workspace entry from the registry by path.
scind workspace forget <path>Arguments:
| Argument | Description |
|---|---|
path |
Registered workspace path to drop |
Behavior:
- Removes the registry entry whose path matches
path, leaving all other entries untouched - For a workspace that was moved or deleted outside Scind, without touching any files on disk
- Unlike
workspace prune(which validates and drops all stale entries) this targets exactly one entry; unlikeworkspace destroyit removes nothing but the registry line
Example:
scind workspace forget ~/workspaces/old-dev
# Forgot "old-dev" (~/workspaces/old-dev)Show detailed information about a workspace, including the computed manifest.
scind workspace show [flags]Flags:
| Flag | Description |
|---|---|
-w, --workspace |
Target workspace (or use context) |
Output: Workspace configuration, applications, computed hostnames, port assignments.
Example:
scind workspace show --workspace=devInitialize a new workspace.
scind workspace init [flags]Flags:
| Flag | Description |
|---|---|
-w, --workspace |
Workspace name (required if not in existing workspace dir) |
--path |
Directory to create workspace in (default: ./{name} or current dir) |
Behavior:
- If run in an empty directory without
--workspace, prompts for name - If run with
--workspace=NAME, creates./NAME/workspace.yamlor./workspace.yamlif--path=. - Creates initial directory structure
- Registers the workspace in
~/.config/scind/workspaces.yaml - Fails if name is already registered to a different path (enforces workspace name uniqueness)
Example (new workspace):
scind workspace init --workspace=dev
# Creates ./dev/workspace.yaml
# Registers "dev" -> ./dev in workspace registryExample (current directory):
cd ~/my-project
scind workspace init --workspace=dev
# Creates ./workspace.yaml with name: dev
# Registers "dev" -> ~/my-project in workspace registryExample (name collision):
scind workspace init --workspace=dev
# Error: Workspace "dev" already registered at ~/workspaces/dev
# Use a different name, or run `scind workspace prune` if that path no longer existsClone all application repositories defined in the workspace.
scind workspace clone [flags]Flags:
| Flag | Description |
|---|---|
-w, --workspace |
Target workspace (or use context) |
-a, --app |
Clone specific app(s) only (repeatable) |
Behavior:
- Reads
repositoryURLs fromworkspace.yaml - Clones each application to its configured path
- Skips applications that already exist locally
- Skips applications with
path: .(single-app workspaces where the application is the workspace root)
Error handling:
- On clone failure (network error, auth failure, invalid URL), aborts immediately
- Partial clones are cleaned up on failure
- Exit code 1 on any failure
Single-app workspace handling:
scind workspace clone
# Skipping myapp: application is workspace root (path: .)
# Cloned: backend -> ./backendGenerate or regenerate Docker Compose override files.
scind workspace generate [flags]Flags:
| Flag | Description |
|---|---|
-w, --workspace |
Target workspace (or use context) |
-a, --app |
Generate for specific app(s) only (repeatable) |
--force |
Regenerate even if files appear up-to-date |
Behavior:
- Reads
workspace.yamland eachapplication.yaml - Generates
.generated/*.override.yamlfiles - Updates
.generated/manifest.yaml - Updates
.generated/state.yamlif needed
Note: Generation happens automatically during workspace up when source files have changed. Use this command for explicit control.
Bring up a workspace (generate overrides if needed, create networks, start containers).
scind workspace up [flags]Flags:
| Flag | Description |
|---|---|
-w, --workspace |
Target workspace (or use context) |
-a, --app |
Start specific app(s) only (repeatable) |
--no-generate |
Skip automatic regeneration |
--force-generate |
Force regeneration even if up-to-date |
-d, --detach |
Run in background (default: true) |
Behavior:
- Detect or require workspace context
- Ensure the
scind-proxynetwork exists; start the proxy when an application in this invocation has a proxied export andproxy.auto_startistrue(its default) (see Proxy Start Conditions) - Ensure workspace network (
{workspace}-internal) exists - Check if override files are stale; regenerate if needed (see Staleness Detection)
- For each application (or specified apps):
- Resolve active flavor
- Execute
docker compose up -dwith appropriate files
- Report status
Example:
scind workspace up --workspace=dev
scind workspace up -a frontend -a backend # With context
scind up # Alias, with contextTear down a workspace (stop containers, remove networks).
scind workspace down [flags]Flags:
| Flag | Description |
|---|---|
-w, --workspace |
Target workspace (or use context) |
-a, --app |
Stop specific app(s) only (repeatable) |
--volumes |
Also remove volumes |
--force |
Skip confirmation for destructive actions |
Behavior:
- For each application (or specified apps):
- Execute
docker compose down
- Execute
- If all apps stopped, optionally remove workspace network
- If
--volumesspecified, remove associated volumes - Prompt before removing volumes that may contain data (unless
--force)
Restart a workspace or specific applications.
scind workspace restart [flags]Flags:
| Flag | Description |
|---|---|
-w, --workspace |
Target workspace (or use context) |
-a, --app |
Restart specific app(s) only (repeatable) |
Behavior: Equivalent to down followed by up. Volumes are always preserved (the internal down does not use --volumes).
Show the running status of a workspace.
scind workspace status [flags]Flags:
| Flag | Description |
|---|---|
-w, --workspace |
Target workspace (or use context) |
Output:
Workspace: dev
Network: dev-internal (created)
Proxy: running
APPLICATION FLAVOR STATUS SERVICES URL
frontend full running 3/3 running https://dev-frontend-web.scind.test
backend full running 5/5 running https://dev-backend-api.scind.test
shared-db default stopped 0/2 running —
Completely remove a workspace.
scind workspace destroy [flags]Flags:
| Flag | Description |
|---|---|
-w, --workspace |
Target workspace (or use context) |
--force |
Skip confirmation prompts and remove application directories |
--keep-apps |
Preserve application directories without prompting |
Behavior:
- Run
workspace down --volumes - Remove
.generated/directory - Prompt before removing application directories (unless
--forceor--keep-apps) - Remove
workspace.yaml - Release any assigned ports
- Remove workspace from registry (
~/.config/scind/workspaces.yaml)
Warning: This is destructive. Without --force or --keep-apps, prompts for confirmation showing what will be removed.
Failure semantics: if any application's teardown in step 1 fails, destroy aborts before removing .generated/, workspace.yaml, port assignments, or the registry entry. Applications that were already stopped stay stopped, but nothing describing the workspace is discarded while resources it owns may still exist — so the operator can retry destroy, or investigate the failing application first, with the workspace still fully described. (Validated by the Xcind proof-of-concept, PR #86.)
Manage applications within workspaces.
List applications in a workspace.
scind app list [flags]Flags:
| Flag | Description |
|---|---|
-w, --workspace |
Target workspace (or use context) |
Output:
NAME FLAVOR STATUS SERVICES PATH
frontend full running 3/3 ./frontend
backend full running 5/5 ./backend
shared-db default stopped 0/2 ./shared-db
Show detailed information about an application.
scind app show [flags]Flags:
| Flag | Description |
|---|---|
-w, --workspace |
Target workspace (or use context) |
-a, --app |
Target application (or use context) |
Output: Application configuration, current flavor, and a unified per-export view. The application's apex URL (https://{app}.{domain}, the short address users type) headlines the report when the primary export is proxied; each export is then listed with its full descriptor—type, service, port, URL, TLS, and whether it is the apex—merging proxied and assigned exports by export name.
$ scind app show --app=backend
Application: backend (workspace: dev)
Flavor: full
Apex URL: https://dev-backend.scind.test → api
EXPORT TYPE SERVICE PORT TLS URL
api proxied api — yes https://dev-backend-api.scind.test (apex)
web proxied web — yes https://dev-backend-web.scind.test
debug assigned api 9229 — —
The per-export descriptor rendered here is defined once in the Port Types Specification; its machine-readable form is the proxiedExports/assignedExports maps of the JSON introspection contract, plus the additive apex/apex_host fields. Which export is the apex follows ADR-0013; reporting the apex URL prominently comes from the Xcind proof-of-concept.
Example:
scind app show --app=backendPrint the URLs for an application's proxied exports.
scind app urls [SERVICE] [flags]Arguments:
| Argument | Description |
|---|---|
SERVICE |
Optional export name to filter to a single export |
Flags:
| Flag | Description |
|---|---|
-w, --workspace |
Target workspace (or use context) |
-a, --app |
Target application (or use context) |
-q, --quiet |
Emit the bare value(s) only, one per line—no headers |
Behavior: Reads from persisted state only (read-only and side-effect-free). With no SERVICE, lists every proxied export; with a SERVICE, prints just that export's URL. When a single value results (a filtered SERVICE, or an app with one proxied export), -q prints a bare scalar suitable for scripting:
# Open the web export in a browser
open "$(scind app urls web -q)"
# https://dev-frontend-web.scind.test
$ scind app urls
EXPORT URL
web https://dev-frontend-web.scind.test
api https://dev-frontend-api.scind.testThe --json form is the proxiedExports map of the JSON introspection contract.
Print the host ports for an application's assigned exports.
scind app ports [SERVICE] [flags]Arguments:
| Argument | Description |
|---|---|
SERVICE |
Optional export name to filter to a single export |
Flags:
| Flag | Description |
|---|---|
-w, --workspace |
Target workspace (or use context) |
-a, --app |
Target application (or use context) |
-q, --quiet |
Emit the bare value(s) only, one per line—no headers |
Behavior: Read-only. Lists assigned host ports, or the single port for a named SERVICE. -q yields a bare scalar for scripting (e.g. psql -p "$(scind app ports db -q)"). The --json form is the assignedExports map of the JSON introspection contract.
Show every export of an application in one unified view, merging proxied and assigned exports by export name.
scind app exports [SERVICE] [flags]Arguments:
| Argument | Description |
|---|---|
SERVICE |
Optional export name to filter to a single export |
Flags:
| Flag | Description |
|---|---|
-w, --workspace |
Target workspace (or use context) |
-a, --app |
Target application (or use context) |
-q, --quiet |
Names only, one per line |
Behavior: Read-only. Renders the full per-export descriptor (type, service, port, URL, TLS, apex) for each export—the same tabular view that headlines scind app show. The --json form is the combined proxiedExports/assignedExports maps of the JSON introspection contract.
Together, app urls, app ports, and app exports give per-app, scriptable introspection to complement the workspace-wide scind urls. Credit to the Xcind proof-of-concept for the per-app scalar introspection surface.
Read a single value out of an application's resolved configuration.
scind app get <path> [flags]Arguments:
| Argument | Description |
|---|---|
path |
Dotted path into the resolved configuration |
Flags:
| Flag | Description |
|---|---|
-w, --workspace |
Target workspace (or use context) |
-a, --app |
Target application (or use context) |
Behavior: Read-only. app get draws from the same single source of truth as --json and scind compose-config — the application metadata plus the resolved Compose document — so a value read here is the value that generated the routing labels. It is a scalar accessor for scripts, not a second resolution path.
Path grammar: a path is one or more segments separated by dots. A segment is a bare key or a quoted key, optionally followed by array indices:
path := segment ( "." segment )*
segment := ( bare | quoted ) index*
bare := [A-Za-z_][A-Za-z0-9_-]*
quoted := '"' ( any character, with \" and \\ escaped ) '"'
index := "[" [0-9]+ "]"
Quote a key that itself contains a dot — Compose labels being the common case:
scind app get 'compose.services.web.labels."traefik.http.routers.dev-frontend-web-https.rule"'
scind app get proxiedExports.web.url
scind app get 'compose.services.web.ports[0]'Output: scalars print raw (no quoting, no trailing structure), so a value can be captured directly into a shell variable. Objects and arrays print as compact JSON.
Exit codes:
| Code | Meaning |
|---|---|
| 0 | The path holds a non-null value (printed) |
| 1 | The path is absent, null, or blocked by a scalar — a general error, per the Exit Codes table |
| 2 | Malformed path — invalid arguments, per the Exit Codes table |
| 3 | Resolved state is unavailable (nothing generated yet) — a configuration error |
An absent path is silent. A path that runs through a scalar (metadata.app.nested where metadata.app is a string) writes a "path is not traversable" line to stderr and still exits 1, so callers that must distinguish the two can read stderr.
Being read-only, app get never generates overrides or starts anything to answer a question; when resolved state does not exist it reports so and points at scind generate.
Credit to the Xcind proof-of-concept for the single-value resolved-config lookup pattern (Xcind PR #85).
Initialize an application configuration in the current directory.
scind app init [flags]Flags:
| Flag | Description |
|---|---|
-a, --app |
Application name (default: current directory name) |
Behavior:
- Creates
application.yamlin current directory - Scans for existing
docker-compose.yamlto suggest exported services - Scaffolds a default flavor pointing at the existing compose file(s) only when they do not already match the conventional names — a project using
compose.yamlordocker-compose.yamlresolves those by convention, soapp initleaves the declaration out rather than restating the default
Use case: Promoting an existing Docker Compose project to a Scind application.
cd ~/my-project
scind app init --app=myapp
# Creates ./application.yamlAdd an application to a workspace.
scind app add [flags]Flags:
| Flag | Description |
|---|---|
-w, --workspace |
Target workspace (or use context) |
-a, --app |
Application name (required) |
--repo |
Git repository URL to clone |
--path |
Custom application path (default: ./{app}). Relative paths resolve from the workspace root; absolute paths and paths outside the workspace tree are allowed |
Behavior:
- Adds application entry to
workspace.yaml - If
--repoprovided, clones repository to path - If
--path=., configures app to use workspace root (single-app workspace) - If the path resolves outside the workspace tree, the application is still a full member of the roster, but context detection cannot reach it — target it with
-w/-a. See Configuration Reference — External Applications.
Single-app workspace naming: The workspace name and app name are independent. You can have workspace dev with app myapi, or create multiple workspaces (dev, review, feature-x) each containing the same app name (myapi). The app name comes from --app; the workspace name comes from workspace init --workspace.
Example:
scind app add --app=api --repo=git@github.com:org/api.git
scind app add --app=main --path=. # Use current directoryRemove an application from a workspace.
scind app remove [flags]Flags:
| Flag | Description |
|---|---|
-w, --workspace |
Target workspace (or use context) |
-a, --app |
Target application (or use context) |
--force |
Skip confirmation, also remove directory |
Behavior:
- Stops application if running
- Removes from
workspace.yaml - Prompts before removing application directory (unless
--force) - Releases any assigned ports
Bring up a single application.
scind app up [flags]Flags:
| Flag | Description |
|---|---|
-w, --workspace |
Target workspace (or use context) |
-a, --app |
Target application (or use context) |
Equivalent to scind workspace up --app=NAME.
Tear down a single application.
scind app down [flags]Flags:
| Flag | Description |
|---|---|
-w, --workspace |
Target workspace (or use context) |
-a, --app |
Target application (or use context) |
--volumes |
Also remove volumes |
Equivalent to scind workspace down --app=NAME.
Restart a single application.
scind app restart [flags]Flags:
| Flag | Description |
|---|---|
-w, --workspace |
Target workspace (or use context) |
-a, --app |
Target application (or use context) |
Behavior: Equivalent to app down followed by app up. Volumes are always preserved.
Show status of a single application.
scind app status [flags]Flags:
| Flag | Description |
|---|---|
-w, --workspace |
Target workspace (or use context) |
-a, --app |
Target application (or use context) |
Example:
scind app status --app=frontendExplain how one application's configuration resolved into generated artifacts and routing.
scind app diagnose [flags]Flags:
| Flag | Description |
|---|---|
-w, --workspace |
Target workspace (or use context) |
-a, --app |
Target application (or use context) |
--json |
Machine-readable output |
Purpose: diagnose answers "why did routing or generation not come out the way I expected for this app?" — a question scind doctor cannot answer, because doctor checks host health (Docker, Compose, the proxy, DNS) and never looks at a single application's resolution. The two are deliberately separate: doctor is host-scoped, diagnose is app-scoped. This capability comes from the Xcind proof-of-concept, where it was built because users had no other way to see why a proxied export failed to produce routing.
Reported: the resolution chain, in the order Scind computed it.
| Section | Content |
|---|---|
| Configuration inputs | Which files resolved and were read (workspace.yaml, application.yaml, env files), with their absolute paths |
| Flavor | The active flavor and which resolution step selected it (CLI flag, state file, default_flavor, or the "default" fallback) |
| Compose files | The resolved compose file list, whether each exists, and whether the list came from a declaration or from convention defaults |
| Exports | Each entry of exported_services as parsed: type, protocol, resolved container port and how it was inferred, TLS mode, visibility, and whether the entry is the apex-bearing export (or why it is not) |
| Assigned ports | The recorded assignment for each assigned export, the requested port, and the allocated host port |
| Generated artifacts | Which files exist under .generated/, whether the completeness marker is present and current, and the staleness verdict with the input that caused it |
Behavior: diagnose is a read-only, side-effect-free command. It reports what the current state is — it never generates overrides, allocates ports, provisions certificates, or starts containers to answer the question. When something has not been generated yet, it says so and names the command that would do it, rather than doing it.
--json output: the JSON Introspection Contract makes two separate promises, and diagnose is covered by one of them, not both. It is bound by the contract's read-only, side-effect-free guarantee. It is not covered by the contract's field-stability guarantee, which extends to the per-export proxiedExports/assignedExports maps and the apex/apex_host fields only. diagnose reports the full resolution chain, so its JSON shape is provisional — it carries one object per section listed in the Reported table above, keyed by section name, with the same fields the text form renders. It will be pinned to a stable contract in a later revision once the section shapes see real use. Tools may consume it for debugging, but should not depend on field stability across versions yet.
Example:
$ scind app diagnose --app=frontend
Application: frontend (workspace: dev)
Configuration
workspace.yaml /Users/beau/workspaces/dev/workspace.yaml
application.yaml /Users/beau/workspaces/dev/frontend/application.yaml
flavor full (from .generated/state.yaml)
compose files docker-compose.yaml ✓, docker-compose.worker.yaml ✓ (declared)
Exports
web proxied https port 3000 (inferred from compose) tls=auto apex ✓
debug assigned port 9229 host 9231
Generated
frontend.override.yaml present
completeness marker present (schema v3, current)
staleness STALE — application.yaml is newer than the override
run 'scind generate' or 'scind up'Manage application flavors (named configurations).
List available flavors for an application.
scind flavor list [flags]Flags:
| Flag | Description |
|---|---|
-w, --workspace |
Target workspace (or use context) |
-a, --app |
Target application (or use context) |
Output:
NAME COMPOSE FILES ACTIVE
lite docker-compose.yaml
full docker-compose.yaml, docker-compose.worker.yaml ✓
debug docker-compose.yaml, docker-compose.debug.yaml
Show the current active flavor for an application.
scind flavor show [flags]Flags:
| Flag | Description |
|---|---|
-w, --workspace |
Target workspace (or use context) |
-a, --app |
Target application (or use context) |
Set the active flavor for an application.
scind flavor set <flavor> [flags]Arguments:
| Argument | Description |
|---|---|
flavor |
Name of flavor to activate |
Flags:
| Flag | Description |
|---|---|
-w, --workspace |
Target workspace (or use context) |
-a, --app |
Target application (or use context) |
Behavior:
- Validates that the application declares the named flavor, before writing anything. An undeclared flavor is rejected with
Active Flavor Not Declaredandstate.yamlis left untouched — recording it first would leave a value that breaks every later command until it is edited out by hand. See Resolution Validity. - Updates
.generated/state.yamlwith the new flavor - Immediately regenerates the affected application's override file
- If the application is running, displays a warning with restart guidance
- Does NOT automatically restart containers
Warning when application is running: If the target application is currently running,
flavor setdisplays a warning explaining that running containers still use the previous flavor and provides the command to apply changes.
After changing flavors:
| Scenario | Command |
|---|---|
| Flavor adds/removes services | scind up (starts new services, stops orphaned services) |
| Flavor changes environment or config | scind app restart -a APP |
Example:
# Change flavor (regenerates config, warns if running)
scind flavor set full --app=backend
# Apply to running application
scind app restart --app=backendManage host port assignments for assigned-type services.
Port Types: Services can expose
proxiedports (through Traefik reverse proxy) orassignedports (direct host binding). Port commands manage assigned ports only; proxied ports are handled automatically through the proxy. See ADR-0007: Port Type System.
List all assigned ports.
scind port list [flags]Flags:
| Flag | Description |
|---|---|
-w, --workspace |
Filter to specific workspace |
-v, --verbose |
Include bind status check |
Output:
PORT WORKSPACE APP SERVICE STATUS
5432 dev shared-db db assigned
6379 dev shared-db cache assigned
8080 dev frontend web assigned
3000 dev backend api assigned
With --verbose:
PORT WORKSPACE APP SERVICE STATUS BOUND
5432 dev shared-db db assigned yes
6379 dev shared-db cache assigned yes
8080 dev frontend web assigned yes
3000 dev backend api assigned no
Show details about a specific port assignment.
scind port show <port>Arguments:
| Argument | Description |
|---|---|
port |
Port number to inspect |
Manually release a port assignment.
scind port release <port> [flags]Arguments:
| Argument | Description |
|---|---|
port |
Port number to release |
Flags:
| Flag | Description |
|---|---|
--force |
Release even if port appears in use |
Manually assign a port (advanced usage).
scind port assign <port> <workspace>/<app>/<service>Arguments:
| Argument | Description |
|---|---|
port |
Port number to assign |
target |
Target in format workspace/app/service |
Garbage collect released and unbound ports.
scind port gc [flags]Flags:
| Flag | Description |
|---|---|
--dry-run |
Show what would be released without doing it |
Behavior:
- Scans port inventory for ports marked as
assignedbut not actually bound - Releases ports whose workspaces/apps no longer exist
- Reports actions taken
Re-scan and update port availability inventory.
scind port scanBehavior:
- Checks all tracked ports for current bind status
- Updates
port_inventoryin global state - Useful after external changes (other processes releasing ports)
Manage the Traefik reverse proxy. The proxy is a shared instance that serves all workspaces on the host.
When proxy.mode is external (ADR-0017), Scind does not own a proxy, and the proxy verbs change accordingly:
| Command | Behavior | Exit |
|---|---|---|
proxy init |
Writes config, removes stale managed artifacts, verifies/creates the configured network | 0 |
proxy up |
Verifies the network, reports a detected proxy-like container, starts nothing | 0 |
proxy up --force / --recreate |
Refuses — would remove a network shared with the external proxy | 1 |
proxy down |
Refuses, except the migration escape hatch documented under scind proxy down |
1 / 0 |
proxy restart |
Refuses — there is no Scind-owned proxy to restart | 1 |
proxy logs |
Refuses, with a docker logs {container} hint |
1 |
proxy status |
External-specific report | 0 |
proxy destroy |
Runs, but never removes the configured shared network | 0 |
Why refuse instead of no-op: these verbs promise actions Scind cannot perform on a proxy it does not own. Exiting 0 having done nothing would report success for a request that was never carried out; a refusal tells the truth and names the mode that caused it.
Bootstrap the proxy configuration. This creates the Traefik Docker Compose project at ~/.config/scind/proxy/.
scind proxy init [flags]Flags:
| Flag | Description |
|---|---|
--force |
Overwrite existing configuration (useful for recovery) |
--domain |
Set proxy domain (default: scind.test) |
--path |
Directory to create proxy in (default: ~/.config/scind/proxy/) |
Behavior:
- Check if proxy configuration already exists
- If exists and no
--force: error with message - If exists and
--force: backup existing config and overwrite
- If exists and no
- Create proxy directory structure (
docker-compose.yaml,traefik.yaml,dynamic/,certs/) - Create the configured proxy Docker network (
proxy.network, defaultscind-proxy) if it doesn't exist - Output next steps (DNS setup, starting proxy)
Example:
$ scind proxy init
Created proxy configuration at ~/.config/scind/proxy/
Next steps:
1. Configure DNS for *.scind.test → 127.0.0.1
(See: scind doctor for DNS verification)
2. Start the proxy:
scind proxy up
$ scind proxy init
Error: Proxy configuration already exists at ~/.config/scind/proxy/
Use --force to overwrite, or --path to create elsewhere.
$ scind proxy init --force
Backed up existing configuration to ~/.config/scind/proxy.backup.20241230/
Created proxy configuration at ~/.config/scind/proxy/Custom domain example:
$ scind proxy init --domain mydev.local
Created proxy configuration at ~/.config/scind/proxy/
Domain set to: mydev.localUnder mode: external: generation steps are skipped entirely — no compose file, no static configuration, no dynamic/tls.yaml, no certificate provisioning. init instead removes the stale managed static configuration and dynamic/tls.yaml, leaves certs/ in place (harmless, and it preserves a user-supplied wildcard across mode flip-flops), and removes the generated compose file only when no container labeled scind.component=proxy is running — while one exists that file is the only handle for stopping it, so init retains it and warns. It then verifies the configured shared network, creating it if absent. See Proxy Infrastructure — External Proxy Mode.
Coolify-style external setup:
$ scind config set proxy.mode external
$ scind config set proxy.network coolify
$ scind config set proxy.http_entrypoint http
$ scind config set proxy.https_entrypoint https
$ scind config set proxy.certresolver letsencrypt
$ scind config set proxy.domain apps.example.com
$ scind proxy init
Proxy mode: external — Scind will not start or configure a proxy.
Network 'coolify' exists.
Applications will emit routers on entrypoints http/https with certresolver 'letsencrypt'.Start the Traefik proxy.
scind proxy up [flags]Flags:
| Flag | Description |
|---|---|
--recreate |
Recreate the proxy network even if it exists |
Behavior:
- Creates the configured proxy network (
proxy.network, defaultscind-proxy) if it doesn't exist - Validates existing network configuration matches expected settings
- Starts Traefik container from proxy configuration
- If proxy configuration doesn't exist, runs
proxy initfirst
Under mode: external: up keeps its "make the proxy layer ready" contract by verifying the shared network and reporting any detected proxy-like container; it starts nothing and exits 0. --recreate (and --force) refuse with exit 1, since recreating a network shared with the external proxy would disconnect that proxy and any unrelated workloads on it.
Network conflict handling:
If the scind-proxy network exists but was created by a different tool or has incompatible settings, proxy up will warn:
Warning: Network 'scind-proxy' exists but may not have been created by Scind.
Driver: bridge (expected: bridge) ✓
Labels: scind.managed not found ⚠
Use 'scind proxy up --recreate' to recreate the network.
Note: Users rarely need to call this directly. workspace up starts the proxy on its own when an application it is bringing up declares a proxied export. Call proxy up explicitly when you have set proxy.auto_start: false, or when you want the proxy running ahead of any application.
Stop the Traefik proxy.
scind proxy downUnder mode: external: down refuses with exit 1 — stopping a proxy Scind does not own is not Scind's to do.
The sole exception is the managed→external migration escape hatch. When both of the following hold, down stops that Scind-managed proxy via its compose file and exits 0:
- a container labeled
scind.component=proxyis running, and - the previously generated managed compose file still exists.
Both predicates are required. The label alone could match a proxy the user ran by hand, which Scind has no mandate to stop; the compose file alone could be stale, describing a proxy that no longer exists. Either one on its own leaves the refusal in place. Together they identify a proxy Scind itself started and still knows how to stop — exactly the case of a host that has just switched from managed to external.
Restart the Traefik proxy.
scind proxy restartUnder mode: external: refuses with exit 1. There is no Scind-owned proxy to restart, and the escape hatch that down offers has no restart counterpart — Scind would not know how to bring the foreign proxy back.
Show proxy status.
scind proxy statusOutput (dashboard enabled):
Mode: managed
Proxy: running
Network: scind-proxy (created)
Dashboard: http://localhost:8080
Entrypoints:
- web: :80
- websecure: :443
Output (dashboard disabled):
Mode: managed
Proxy: running
Network: scind-proxy (created)
Dashboard: disabled
Entrypoints:
- web: :80
- websecure: :443
Output (mode: external):
Mode: external
Network: coolify (present)
Entrypoints:
- http (HTTP)
- https (HTTPS)
Certresolver: letsencrypt
Detected proxy container: coolify-proxy (running)
The external report omits Traefik container state and the dashboard URL entirely — Scind neither runs that container nor knows whether a dashboard is exposed. The detected-proxy line is best-effort: it reports a proxy-like container found on the configured network, and its absence is informational, not an error.
Note: The dashboard URL reflects the configured port from proxy.yaml (dashboard.port, default 8080). If dashboard.enabled is false, the dashboard line shows "disabled".
Machine-readable output: --json carries a mode field in both modes, so a consumer never has to infer the mode from which other fields happen to be present. The managed payload additionally carries container state and dashboard URL; the external payload carries network presence, entrypoint names, certresolver, and the detected container.
Remove the Scind-managed proxy and its generated state.
scind proxy destroy [--purge] [--force]Flags:
| Flag | Description |
|---|---|
--purge |
Also remove the proxy configuration directory (~/.config/scind/proxy/) |
--force |
Skip the confirmation prompt |
Behavior:
- Stop the managed proxy container.
- Remove the generated Traefik project and its state directory.
- Remove
~/.config/scind/proxy/only with--purge. By default the configuration survives, so a laterscind proxy initrecovers the user's settings rather than starting from defaults.
Port assignments are lost. The generated proxy state holds the assigned-port inventory. Destroying it therefore forgets every workspace's port assignments at once — each one receives new host ports on the next up. The confirmation prompt counts the bindings it is about to forget; --force skips that prompt, so scripted destruction drops them silently. See State Management — Port Status Transitions.
Under mode: external: destroy still runs, because it targets Scind's own generated state, which exists in external mode too. It stops a retained Scind-managed proxy via the previously generated compose file — leaving generated state intact for a retry if that teardown fails, since the compose file is the only handle for stopping that container — and then removes the generated state. It must not remove the configured shared network: that network is owned by the external proxy and may carry unrelated workloads.
Credit to the Xcind proof-of-concept for the proxy-disposal semantics, including the config-survives-by-default split and the external-mode retention rule (Xcind PR #86).
Manage Scind configuration.
Show all configuration values.
scind config showOutput:
proxy:
domain: scind.test
paths:
global_config: ~/.config/scind/proxy.yaml
global_state: ~/.config/scind/state.yamlGet a specific configuration value.
scind config get <key>Example:
scind config get proxy.domain
# scind.testSet a configuration value.
scind config set <key> <value>Example:
scind config set proxy.domain local.testShow configuration file locations.
scind config pathOutput:
Global config: ~/.config/scind/proxy.yaml
Global state: ~/.config/scind/state.yaml
Open the global configuration file in your default editor.
scind config editBehavior:
- Opens
~/.config/scind/proxy.yamlin$EDITOR(or$VISUAL, or falls back tovi) - Creates the config file with defaults if it doesn't exist
Scind provides a scind-compose binary for direct Docker Compose interaction with automatic context awareness. It is installed alongside scind, resolves the workspace, application, and compose files itself, then execs docker compose with the correct project name and -f files. Nothing needs to be sourced to use it; scind init-shell installs only its completion.
For full documentation on scind-compose and shell integration, see the Shell Integration Specification.
scind-compose [-w WORKSPACE] [-a APP] <docker compose args…>Flags:
| Flag | Description |
|---|---|
-w, --workspace |
Target workspace (or use context) |
-a, --app |
Target application (or use context) |
Argument parsing stops consuming Scind flags at the first positional argument or unrecognized flag; everything after that is passed straight to docker compose.
Exit codes: 5 when context cannot be resolved (the error goes to stderr directly); otherwise Docker Compose's own exit code, since scind-compose execs it.
$ cd ~/workspaces/dev/frontend
$ scind-compose exec php bash
$ scind-compose -a backend logs -fOutput the Docker Compose command prefix for the current context.
Not load-bearing. Nothing in Scind's shell integration consumes this command —
scind-composeresolves context in-process.compose-prefixis retained for scripting consumers that want the resolved-p/-ftext for their own command lines.
scind compose-prefix [flags]Flags:
| Flag | Description |
|---|---|
-w, --workspace |
Target workspace (or use context) |
-a, --app |
Target application (or use context) |
Note: There is no
--flavorflag forcompose-prefix. Flavor changes require regeneration and can impact running applications. Usescind flavor setto change the active flavor before runningscind-compose.
Output:
$ cd ~/workspaces/dev/frontend
$ scind compose-prefix
docker compose -p dev-frontend -f '/home/user/workspaces/dev/frontend/docker-compose.yaml' -f '/home/user/workspaces/dev/.generated/frontend.override.yaml'Error Handling:
If context cannot be resolved, exits with code 5:
$ cd ~
$ scind compose-prefix
Error: No application context detected.
Either:
1. Run from within an application directory
2. Specify explicitly with -w and -a flags
Available workspaces: scind workspace listCallers must branch on the exit code, not on empty output.
Output the fully-resolved, flattened Docker Compose configuration for an application to stdout or a file. This is docker compose config for the resolved Scind context: the active flavor's base compose files plus the generated override, merged and interpolated into a single canonical document.
scind compose-config [flags]Flags:
| Flag | Description |
|---|---|
-w, --workspace |
Target workspace (or use context) |
-a, --app |
Target application (or use context) |
-o, --output <path> |
Write to path instead of stdout |
Behavior:
- Resolves the active flavor's compose files and the
.generated/override, then emits the merged, fully-interpolated result - Distinct from
scind generate, which writes override deltas to a fixed.generated/path;compose-configproduces the complete resolved document on demand, to stdout or an arbitrary location - Read-only with respect to Scind state (does not regenerate as a side effect)
Dev Container consumer path: The primary use is baking a resolved configuration into a snapshot that a devcontainer.json references, so the container build sees one self-contained compose file with the project name and services already resolved:
scind compose-config -a backend -o .devcontainer/compose.snapshot.yaml
# .devcontainer/devcontainer.json → "dockerComposeFile": "compose.snapshot.yaml"Credit to the Xcind proof-of-concept (Xcind ADR-0012) for the resolved-config export and its Dev Container consumer path.
Output shell integration script for the specified shell. This script registers completion; scind-compose is a binary on PATH and needs nothing sourced to run.
scind init-shell {bash|zsh|fish}Installation:
# Bash
scind init-shell bash >> ~/.bashrc
# Zsh
scind init-shell zsh >> ~/.zshrc
# Fish
scind init-shell fish >> ~/.config/fish/conf.d/scind.fishProvides:
- Tab completion for
scind-compose, delegating todocker __complete compose …with a hardcoded subcommand fallback for hosts whosedockerCLI lacks it - Completion of
-w/-avalues from Scind's own workspace and application lists
Example Usage (after installation):
# From within an application directory
$ cd ~/workspaces/dev/frontend
$ scind-compose exec node bash
$ scind-compose logs -f
# From workspace root with explicit app
$ cd ~/workspaces/dev
$ scind-compose -a backend ps
# From anywhere with explicit workspace and app
$ scind-compose -w dev -a frontend up -dGenerate real, executable docker and docker-compose wrapper scripts for the current context.
scind generate-wrappers [flags]Flags:
| Flag | Description |
|---|---|
-w, --workspace |
Target workspace (or use context) |
-a, --app |
Target application (or use context) |
--dir <path> |
Directory to write the wrapper scripts into (default: ./.scind/bin) |
Behavior:
- Writes two executable scripts—
dockeranddocker-compose—into--dir, each embedding the resolved project name and compose files for the context (the same-p/-fset thatscind compose-prefixemits) - Invoking a wrapper on PATH runs the corresponding Docker command with the Scind project name and
-ffiles already injected, then passes the remaining arguments through - The scripts are real files on disk named
dockeranddocker-compose, so they work for tools that exec those exact names from PATH and offer no setting for a different command
Use case: JetBrains IDEs, CI runners, and other harnesses resolve docker/docker-compose from PATH and cannot be told to call scind-compose instead. Point such a tool at the generated --dir (prepend it to PATH, or set the IDE's Docker executable path) and it becomes Scind-aware transparently.
$ scind generate-wrappers -a backend --dir .scind/bin
Wrote .scind/bin/docker
Wrote .scind/bin/docker-compose
# Any tool that execs `docker-compose` from this PATH is now workspace-aware
$ PATH=".scind/bin:$PATH" docker-compose psThis complements, not replaces, scind-compose. Anywhere you control the command name — shells, scripts, CI — call scind-compose (nothing to regenerate when context changes); the wrapper scripts exist specifically for tools hardwired to the docker/docker-compose names. See the Shell Integration Specification for details. Credit to the Xcind proof-of-concept.
Render a context-aware prompt segment for the current workspace/app, and generate a ready-to-paste Starship snippet that calls it.
scind prompt [flags]
scind prompt --generate starship [flags]Flags:
| Flag | Description |
|---|---|
--generate <shell-tool> |
Emit an integration snippet instead of rendering. Currently: starship. |
--print <field> |
Print a single field only: workspace, app, apex, or url |
--detect |
Availability probe: exit 0 if a Scind context is present, non-zero otherwise. Prints nothing. |
-q, --quiet |
Suppress decoration; bare segment text only |
Behavior:
- Renders the current workspace/app plus a clickable apex URL, emitted as an OSC 8 hyperlink so terminals that support it make the URL clickable while others degrade to plain text
- Uses a fast context-only detection path: it resolves workspace/app/apex from directory context and persisted state and stops before any expensive Docker or introspection work (no container queries, no proxy calls). This path targets sub-500 ms so it is safe to run on every prompt render.
--detectexposes just the context probe, so a prompt tool can decide whether to show the segment at all without paying for a render--print <field>returns one value for scripting or hand-rolled prompt formats
Starship generation:
$ scind prompt --generate starship
# Add to ~/.config/starship.toml:
[custom.scind]
command = "scind prompt --quiet"
when = "scind prompt --detect"
format = "[$output]($style) "The generated custom module gates on scind prompt --detect (cheap, no output) and renders with scind prompt --quiet, so the segment appears only inside a Scind context. See the Shell Integration Specification for the detection-path contract. Credit to the Xcind proof-of-concept for the context-aware prompt segment.
For common operations, these aliases are provided:
| Alias | Equivalent |
|---|---|
scind up |
scind workspace up |
scind down |
scind workspace down |
scind ps |
scind workspace status |
scind generate |
scind workspace generate |
All aliases accept the same flags as their full forms and support context detection.
Validate configuration files.
scind validate [flags]Flags:
| Flag | Description |
|---|---|
-w, --workspace |
Target workspace (or use context) |
-a, --app |
Target application (or use context) |
Behavior:
- Validates YAML syntax
- Checks schema compliance
- Verifies referenced files exist
- Reports errors with file locations
Example:
scind validate --workspace=dev
scind validate --workspace=dev --app=frontendCheck system health and requirements.
scind doctorScope: doctor is host-scoped — it checks Docker, Compose, the proxy, and DNS, the things shared by every workspace on the machine. It does not explain a single application's configuration or routing; use scind app diagnose for that.
Output:
Checking Scind environment...
✓ Docker: running (version 24.0.7)
✓ Docker Compose: available (version 2.23.0)
✓ Proxy mode: managed
✓ Proxy network: created
✓ Traefik: running
✓ Config directory: ~/.config/scind
✓ Domain resolution: scind.test → 127.0.0.1
✓ Workspace domains:
- dev-frontend-web.scind.test → 127.0.0.1
- dev-backend-api.scind.test → 127.0.0.1
All checks passed.
Under mode: external: the proxy-mode line reports external, and the Traefik: running check is replaced by a hard Proxy network: present diagnostic — generated overlays declare that network external: true and fail to start without it, so its absence is a real failure, not a warning. A best-effort informational line reports any detected proxy-like container on that network; not finding one is not a failure, since Scind cannot know how the host proxy is labeled.
✓ Proxy mode: external
✓ Proxy network: coolify (present)
ℹ Detected proxy container: coolify-proxy (running)
DNS checking behavior:
- Uses the system DNS resolver (respects
/etc/hostsand/etc/resolv.conf) - Timeout: 5 seconds per query
- Checks base domain (
scind.test) resolution - If workspaces exist, checks all public proxied hostnames from workspace manifests
- If no workspaces exist, checks a test subdomain (
check-{timestamp}.scind.test) to verify wildcard configuration
Offline/air-gapped environments: DNS checks may fail in environments without network access. Use /etc/hosts entries or a local dnsmasq configuration for offline development.
Wildcard DNS warning (when base resolves but subdomains don't):
⚠ Wildcard DNS not configured. Individual hostnames may not resolve.
Configure dnsmasq: address=/scind.test/127.0.0.1
Open a service URL in the default browser.
scind open [flags]Flags:
| Flag | Description |
|---|---|
-w, --workspace |
Target workspace (or use context) |
-a, --app |
Target application (or use context) |
--service |
Specific exported service (default: first web service) |
List accessible URLs for a workspace.
scind urls [flags]Flags:
| Flag | Description |
|---|---|
-w, --workspace |
Target workspace (or use context) |
-v, --verbose |
Expand to the full per-export URL list |
Output: For each application, the apex URL—the short {app}.{domain} address users actually type—is reported for the primary proxied export:
APP APEX URL EXPORTS
frontend https://dev-frontend.scind.test web
backend https://dev-backend.scind.test web, api
Reporting prefers the apex URL because it is the address developers share and paste. The apex is shown only for applications whose primary export is proxied (assigned-port primaries have no advertised hostname). The full per-export URL list stays in the detailed view (scind urls --verbose, or scind app urls for a single app):
$ scind urls --verbose
APP EXPORT URL
frontend web https://dev-frontend-web.scind.test
backend web https://dev-backend-web.scind.test
backend api https://dev-backend-api.scind.test
Which export is primary is decided by the apex selection rules in ADR-0013; this command only chooses which URL to display.
JSON fields: The JSON introspection contract is extended with two additive, per-application fields, derived from the same source as the scind.apex.* Docker labels:
| Field | Description |
|---|---|
apex |
Apex URL for the primary proxied export (https://{app}.{domain}), or null if the primary is assigned or the application sets apex: false |
apex_host |
Apex hostname ({app}.{domain}), or null under the same two conditions |
Credit to the Xcind proof-of-concept for preferring the apex URL in reporting.
All list and show commands support multiple output formats:
| Flag | Format | Description |
|---|---|---|
| (default) | Table | Human-readable aligned columns |
--json |
JSON | Machine-readable JSON |
--yaml |
YAML | Machine-readable YAML |
--quiet |
Names | Just names/IDs, one per line |
Example:
$ scind workspace list --json
[
{"name": "dev", "apps": 3, "status": "running"},
{"name": "review", "apps": 3, "status": "stopped"}
]
$ scind workspace list --quiet
dev
review--json output is a stable contract, not a serialization of whatever the table happens to render. The structured data Scind uses to generate Traefik routing labels is the same data emitted by --json and consumed by read/show commands, so reported values and generated routing cannot drift—there is a single source of truth for both.
For any command that reports exported services, the --json payload keys exports by export name under two maps:
| Field | Description |
|---|---|
proxiedExports |
Map of export name → proxied descriptor (hostname, proxy URL, protocol, TLS). Backs the scind.* Traefik routing labels. |
assignedExports |
Map of export name → assigned descriptor (internal alias, assigned host port). |
{
"workspace": "dev",
"app": "frontend",
"apex": "https://dev-frontend.scind.test",
"apex_host": "dev-frontend.scind.test",
"proxiedExports": {
"web": {
"type": "proxied",
"service": "web",
"host": "dev-frontend-web.scind.test",
"url": "https://dev-frontend-web.scind.test",
"protocol": "https",
"tls": true
}
},
"assignedExports": {
"debug": {
"type": "assigned",
"service": "web",
"host": "dev-frontend.scind.internal",
"port": 9229
}
}
}The per-export descriptor (the value of each map entry) is defined once in the Port Types Specification; commands render subsets of it but never invent fields.
scind app get is the single-value getter over this same payload, and is bound by both of the promises below: the fields it addresses are the field-stable ones described here, and reading one is side-effect-free.
This contract makes two distinct promises: the field stability of the payload described above, and the read-only guarantee below. They have different scopes — diagnose is bound by the read-only guarantee but its payload is provisional, outside the field-stability promise.
Read-only commands are side-effect-free. show, urls, ports, diagnose, and the per-app introspection commands resolve entirely from persisted state (.generated/, the workspace registry, global state) and configuration. They must never trigger override generation, certificate provisioning, or proxy/container startup as a side effect of being asked to report a value. If the underlying state has not been generated yet, a read-only command reports what is known and points the user to scind generate / scind up rather than performing that work implicitly.
Credit to the Xcind proof-of-concept (Xcind ADR-0015) for the single-contract model that backs labels and introspection alike.
Generate shell completion scripts.
scind completion {bash|zsh|fish}Subcommands:
| Command | Description |
|---|---|
completion bash |
Generate Bash completion script |
completion zsh |
Generate Zsh completion script |
completion fish |
Generate Fish completion script |
Installation:
# Bash
scind completion bash > /etc/bash_completion.d/scind
# Zsh
scind completion zsh > "${fpath[1]}/_scind"
# Fish
scind completion fish > ~/.config/fish/completions/scind.fishScind provides two types of shell integration:
- Standard CLI completion: Completions for the
scindcommand itself - Docker Compose passthrough: Delegated completion for the
scind-composebinary
For complete documentation on shell integration, including scind-compose and its completion delegation, see the Shell Integration Specification.
Install completion scripts for the scind command:
# Bash
scind completion bash > /etc/bash_completion.d/scind
# Zsh
scind completion zsh > "${fpath[1]}/_scind"
# Fish
scind completion fish > ~/.config/fish/completions/scind.fishCompletion Features:
- Command and subcommand completion
- Flag completion with descriptions
- Dynamic completion for
--workspace(fromscind workspace list -q) - Dynamic completion for
--app(fromscind app list -q) - Flavor name completion
- Port number completion
For both CLI completion and scind-compose completion:
# Bash - includes scind completion + scind-compose completion
scind init-shell bash >> ~/.bashrc
# Zsh
scind init-shell zsh >> ~/.zshrc
# Fish
scind init-shell fish >> ~/.config/fish/conf.d/scind.fishThis provides:
- All standard
scindCLI completions - Tab completion for the
scind-composebinary, delegating to Docker's own completion
scind-compose itself needs no shell integration — it is an executable on PATH.
| Variable | Description | Default |
|---|---|---|
SCIND_CONFIG |
Path to global config file | ~/.config/scind/proxy.yaml |
SCIND_STATE_DIR |
State file directory | ~/.config/scind |
SCIND_WORKSPACE |
Default workspace (overrides context detection) | — |
NO_COLOR |
Disable colored output | — |
SCIND_DEBUG |
Enable debug logging | — |
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | General error |
| 2 | Invalid arguments or flags |
| 3 | Configuration error |
| 4 | Docker/Compose error |
| 5 | Context detection failed (workspace/app not found) |
Commands that require Docker check for availability upfront. If Docker is not installed or not running:
Error: Docker is not installed or not running.
Run 'scind doctor' for setup guidance.
Exit code: 4
mkdir ~/workspaces && cd ~/workspaces
scind workspace init --workspace=dev
cd dev
scind app add --app=frontend --repo=git@github.com:org/frontend.git
scind app add --app=backend --repo=git@github.com:org/backend.git
scind up
scind urlscd ~/my-docker-project
scind workspace init --workspace=dev
scind app init --app=myapp
# Edit application.yaml to define exported_services
scind upcd ~/workspaces/dev/frontend
# Start your day
scind up # Brings up entire dev workspace
# Work on frontend
scind-compose logs -f # Tail frontend logs (context detected)
scind app restart # Restart after changes
# Direct Docker Compose interaction (uses scind-compose)
scind-compose exec node bash # Shell into container
scind-compose exec node npm run dev # Run npm command
# Check on another app
scind app status -a backend
scind-compose -a backend logs --tail=50
scind-compose -a backend exec node npm test
# End of day
scind down# scind-compose provides context-aware docker compose access
cd ~/workspaces/dev/frontend
# These are equivalent:
scind-compose exec node bash
# ...to running:
docker compose -p dev-frontend \
-f ~/workspaces/dev/frontend/docker-compose.yaml \
-f ~/workspaces/dev/.generated/frontend.override.yaml \
exec node bash
# Target different app from workspace root
cd ~/workspaces/dev
scind-compose -a backend logs -f api
# Full docker compose functionality with tab completion
scind-compose build --no-cache php
scind-compose run --rm php composer installscind flavor list -a backend
scind flavor set full -a backend
scind app restart -a backendscind port list
scind port list --verbose # Check bind status
scind port gc # Clean up stale assignments