.TH DCSCTL 1 "2026" "User Commands"
.SH NAME
dcsctl \- control-plane CLI for Docker Compose and Docker Swarm stacks
.SH SYNOPSIS
.B dcsctl
\fIcommand\fR [\fIarguments\fR] [\fIflags\fR]
.SH DESCRIPTION
.B dcsctl
provides a structured control-plane for managing Docker Compose and Docker
Swarm projects. It enforces a consistent file and directory layout,
manages environment variable layering across stack and per-service
scopes, handles bind-mount permission enforcement, and supports
deploying to Docker Swarm with automatic compose fragment merging
and variable resolution.
.PP
Projects operate in one of two modes:
.TP
.B compose mode
(legacy) A flat layout with a single
.I docker-compose.yml
at the project root and shared
.IR service.env / service.secrets.env
files. Managed with
.BR "dcsctl run" ", " "dcsctl up" ", " "dcsctl down" .
.TP
.B swarm mode
(default for new projects) Each service lives in its own subdirectory
under
.IR services/ ,
with per-service compose fragments and env files. At deploy time,
fragments are merged, environment variables resolved, and the result
written as
.I docker-compose.resolved.yml
for use with
.BR "docker stack deploy" .
Managed with
.BR "dcsctl deploy" " and " "dcsctl down" .
.PP
Mode is detected automatically: if a project has a
.I services/
directory, it is treated as swarm mode; otherwise compose mode.
.SH PROJECT LAYOUT
.SS Swarm mode (default)
.nf
    ~/.dcs/<context>/compose/<project>/
    \(ba\(em .env                          stack-level orchestration vars
    \(ba\(em services/
    \(ba   \(ba\(em traefik/
    \(ba   \(ba   \(ba\(em compose.yml          service compose fragment
    \(ba   \(ba   \(ba\(em service.env          service runtime config
    \(ba   \(ba   \(ba\(em service.secrets.env  service secrets
    \(ba   \(ba\(em app/
    \(ba       \(ba\(em compose.yml
    \(ba       \(ba\(em service.env
    \(ba       \(ba\(em service.secrets.env
    \(ba\(em docker-compose.resolved.yml   generated at deploy time
    \(ba\(em secrets/
    \(ba\(em .gitignore
.fi
.SS Compose mode (legacy)
.nf
    ~/.dcs/<context>/compose/<project>/
    \(ba\(em docker-compose.yml
    \(ba\(em .env
    \(ba\(em service.env
    \(ba\(em service.secrets.env
    \(ba\(em secrets/
    \(ba\(em .gitignore
.fi
.SH COMMANDS
.SS Project creation
.TP
.BI "dcsctl new " "project " "[flags]"
Create a new project. By default creates a swarm-mode layout with an
initial service named
.BR app .
.RS
.TP
.B \-\-compose
Create a legacy flat compose layout instead.
.TP
.BI \-\-service " name"
Name the initial service (default:
.BR app ).
Only applies in swarm mode.
.TP
.BR \-v ", " \-\-verify
Run verification after creating the project.
.TP
.B \-\-verbose
Verbose verification output (used with
.BR \-\-verify ).
.RE
.SS Deployment
.TP
.BI "dcsctl deploy " "project " "[flags]"
Merge all service compose fragments, resolve environment variables,
write
.IR docker-compose.resolved.yml ,
and run
.BR "docker stack deploy" .
Only available for swarm-mode projects.
.RS
.TP
.BR \-v ", " \-\-verify
Run verification before deploying.
.TP
.B \-\-verbose
Verbose verification output.
.RE
.TP
.BI "dcsctl up " "project " "[flags]"
Alias for
.BR "dcsctl run " "\fIproject\fR up -d" .
Only available for compose-mode projects. Swarm-mode projects should
use
.BR "dcsctl deploy" .
.RS
.TP
.BR \-v ", " \-\-verify
Run verification before starting.
.RE
.TP
.BI "dcsctl stop " project
Scale all services in a deployed swarm stack to 0 replicas, leaving the
stack definition in place. Use
.BR "dcsctl deploy"
to resume. Only available for swarm-mode projects.
.TP
.BI "dcsctl down " project
Bring down a project. For compose-mode projects, runs
.BR "docker compose down" .
For swarm-mode projects, runs
.BR "docker stack rm" .
.TP
.BI "dcsctl run " "project " "[docker compose args...]"
Run docker compose with the project's context and environment files.
Compose-mode only. All arguments after the project name are passed
directly to
.BR "docker compose" .
.TP
.BI "dcsctl reload " project
Down, rebuild, then up a project (compose mode).
.SS Service management
.TP
.BI "dcsctl service add " "project service-name"
Add a new service to a swarm-mode project. Creates the service
subdirectory with compose fragment template, service.env, and
service.secrets.env.
.TP
.BI "dcsctl service ls " project
List services in a swarm-mode project.
.SS Verification
.TP
.BI "dcsctl verify " "project " "[flags]"
Verify and enforce host permissions for bind-mounted appdata
directories. Applies compose fixups (docker.sock group_add,
single-service normalization). For swarm-mode projects, checks
all service fragments.
.RS
.TP
.B \-\-verbose
Show current vs expected ownership/mode while verifying.
.RE
.SS Editing
.TP
.BI "dcsctl edit " "project " "[flags]"
Open a project file in
.BR $EDITOR .
Defaults to the compose file.
.RS
.TP
.BR \-e ", " \-\-env
Edit the stack-level .env file.
.TP
.BR \-r ", " \-\-runtime
Edit service.env (or per-service service.env if
.B \-\-service
is specified).
.TP
.BR \-s ", " \-\-secret
Edit service.secrets.env (or per-service service.secrets.env if
.B \-\-service
is specified).
.TP
.BI \-\-service " name"
Target a specific service's files (swarm mode). When combined with
.B \-\-env
, always edits the stack-level .env.
.RE
.SS Secrets
.TP
.BI "dcsctl secret add " "project name"
Create or edit
.IR secrets/<name>.txt
in
.BR $EDITOR .
.SS Import
.TP
.BI "dcsctl import " "project compose-path " "[flags]"
Import an existing docker-compose.yml into a DCS project.
Routes environment variables to the appropriate DCS layers.
.RS
.TP
.BI \-\-env\-file " path"
Additional env file to ingest alongside env_file references
found in the compose.
.TP
.B \-\-strict
Fail if the compose violates the template contract after import.
.TP
.B \-\-swarm
Import as a swarm project, splitting each service into its own
subdirectory under
.IR services/ .
.RE
.SS Project management
.TP
.BI "dcsctl rename " "project new-name"
Rename a project directory and update all env metadata references.
.TP
.BI "dcsctl dir " "project " "[service]"
Print the resolved compose project directory path. If
.I service
is specified and the project is in swarm mode, prints the path to
.IR services/<service>
instead.
.TP
.B dcsctl ls
List all running compose stacks (alias for
.BR "docker compose ls" ).
.SS Context management
.TP
.BI "dcsctl context init " "[context]"
Initialize
.I ~/.dcs/<context>
with
.I env.system
and
.IR compose/ .
If no context is specified, uses the current Docker context.
.SH ENVIRONMENT
.TP
.B DCS_ROOT
Base directory for all DCS contexts. Defaults to
.IR ~/.dcs .
.TP
.B DCS_CONTEXT_ROOT
Override the context root directory. Defaults to
.IR $DCS_ROOT/<context> .
.TP
.B EDITOR
Editor used by
.B edit
and
.B secret add
commands. Falls back to
.BR vi .
.SH FILES
.TP
.I ~/.dcs/<context>/env.system
Context-level environment overrides (HOST_DATA_ROOT, APPDATA_UID, etc.).
.TP
.I ~/.dcs/<context>/compose/<project>/.env
Stack-level orchestration variables (DCS_PROJ_NAME, DCS_STACK_NAME,
DCS_NET_NAME, HOST_DATA_ROOT, BASE_DIR).
.TP
.I services/*/compose.yml
Per-service compose fragments (swarm mode).
.TP
.I services/*/service.env
Per-service runtime configuration (swarm mode).
.TP
.I services/*/service.secrets.env
Per-service secrets (swarm mode). Not committed to version control.
.TP
.I docker-compose.resolved.yml
Fully resolved compose file generated by
.BR deploy .
All variables substituted, env_file directives inlined. Not committed
to version control.
.SH EXIT STATUS
.TP
0
Success.
.TP
>0
Failure. Error message printed to stderr.
.SH EXAMPLES
Create a new swarm-mode project:
.PP
.nf
    dcsctl new mystack
.fi
.PP
Create with a custom initial service name:
.PP
.nf
    dcsctl new mystack --service traefik
.fi
.PP
Create a legacy compose-mode project:
.PP
.nf
    dcsctl new mystack --compose
.fi
.PP
Add a service to a swarm project:
.PP
.nf
    dcsctl service add mystack redis
.fi
.PP
Deploy a swarm project:
.PP
.nf
    dcsctl deploy mystack
    dcsctl deploy mystack --verify
.fi
.PP
Edit a specific service's env:
.PP
.nf
    dcsctl edit mystack --service traefik --runtime
.fi
.PP
Import an existing compose as a swarm project:
.PP
.nf
    dcsctl import mystack /path/to/docker-compose.yml --swarm
.fi
.PP
Run docker compose commands (compose mode):
.PP
.nf
    dcsctl run myapp logs -f
    dcsctl up myapp --verify
    dcsctl down myapp
.fi
.SH SEE ALSO
.BR docker (1),
.BR docker-compose (1)