Skip to main content

​
crewship apply

Apply a YAML manifest that describes a crew or workspace. Re-running apply is idempotent and convergent: missing resources are created, drifted ones updated, and resources that disappeared from the manifest are deleted (with confirmation). Mutations go through normal REST endpoints so RBAC, audit logging, and WebSocket events fire the same way they would for an interactive user. 
crewship apply --file <path> [flags]
For the narrative tour and the manifest format, see Guides → Workspace Manifests.

​
Flags

FlagDefaultPurpose
--file <path>(required)Path to manifest YAML/JSON. Use - to read from stdin (capped at 4 MiB; split larger files).
--dry-runfalseValidate, render the plan, and exit without mutating.
--strictfalseFail if any resource in the manifest already exists. Use in CI when you require a fresh workspace.
--replacefalseDelete every matching resource before recreating it. Destructive; prompts unless --yes.
--from-envfalseRead credential values from the process environment (var name = credential’s env: field).
--secrets-file <path>""Load credential values from a KEY=VALUE file. Comments (#) and quoted values supported.
--skip-test-gatefalseForward skip_test_gate: true on routine save so apply can ship a brand-new routine without first running it. Server gates the field on OWNER/ADMIN role; MANAGER+ callers get the standard “fresh passing test_run within 5 minutes” requirement.
-y, --yesfalseSkip confirmation prompts. Required when running in a non-TTY (CI) with destructive operations.
--strict and --replace are mutually exclusive. Apply also requires an authenticated session (crewship login) and a workspace context — both are inherited from the current CLI profile. Use --skip-test-gate when applying a manifest whose routine depends on credentials that are still PENDING from the same apply: the test_run would attempt to invoke the routine before its credentials exist, fail, and block save. Operators with OWNER/ADMIN role bypass the gate; everyone else must seed the credentials first and re-run apply without the flag.

​
Examples

​
Idempotent re-apply

crewship apply --file team.yaml --from-env
The most common shape. Reads credential values from env vars matching each env: entry in the manifest. Re-running converges drift.

​
Dry-run as a CI check

crewship apply --file team.yaml --dry-run
Prints the plan, never mutates. Exit code is 0 unless validation fails. Useful as a PR check that catches “this manifest is malformed before review”.

​
Strict mode for ephemeral workspaces

crewship apply --file team.yaml --strict --from-env --yes
Use when you spin up a brand-new workspace per branch — strict catches the case where a previous run wasn’t cleaned up.

​
Replace an existing crew

crewship apply --file team.yaml --replace
Deletes anything matching the manifest’s slugs and recreates from scratch. Use when you’ve broken the schema so badly that upsert can’t reconcile.

​
Read from stdin

cat team.yaml | crewship apply --file -
Useful for piping from sed, op inject, or a templating step.

​
KEY=VALUE secrets file

secrets.env: 
# Lines starting with # are comments (only on their OWN line —
# inline trailing comments after a value become part of the value).
ANTHROPIC_API_KEY=sk-ant-…
# Surrounding single OR double quotes are stripped:
GH_TOKEN="ghp_…"
SLACK_BOT_TOKEN='xoxb-…'
The format mirrors Docker Compose’s --env-file: no env-var expansion happens, the file is the source of truth. 
crewship apply --file team.yaml --secrets-file ./secrets.env --yes

​
Plan + confirm flow

Apply is two-pass: it computes the full plan first, prints it, asks for confirmation on anything destructive, and only then executes. 
$ crewship apply --file team.yaml

Plan:
  + credential ANTHROPIC_API_KEY (ANTHROPIC)
  + crew code-review
  + skill house-style (workspace)
  + agent code-review/daniel
  ~ agent code-review/petra        ← prompt body changed
  - agent code-review/old-bot      ← in workspace, not in manifest

Plan includes 1 destructive operation. Continue? [y/N] y

Applied: 4 created, 1 updated, 0 unchanged, 1 deleted.

PENDING credentials (set values in the UI, or via 'crewship credential update'):
  - ANTHROPIC_API_KEY
The leading character on each line tells you the action:
MarkerMeaning
+Create — resource is in the manifest but missing in the workspace
~Update — drift between manifest and current state
=Unchanged — matches
-Delete — exists in workspace, manifest doesn’t declare it

​
Credential resolution

Manifests never carry secret values. crewship apply resolves the env: slot through a chain of sources, in order:
  1. --secrets-file <path> if supplied
  2. --from-env (process environment) if supplied
  3. Otherwise the credential is created as status=PENDING and printed at the end
PENDING credentials never inject their placeholder into the agent’s environment. Agents that need a pending credential fail with credential not configured until you set the value through the UI or crewship credential update.

​
What gets deleted on sync

Resources synced (= deleted when missing from the manifest, with confirmation):
  • crews (in workspace bundles)
  • agents within each declared crew
  • agent skill bindings
  • agent credential bindings
  • MCP servers on each declared crew
Resources not synced (additive only):
  • skills at workspace scope — drop them via crewship skill rm
  • credentials themselves — drop them via UI or crewship credential delete

​
Exit codes

CodeMeaning
0Success (apply completed, or dry-run validated cleanly)
1Generic failure (validation, network, partial apply)
apply doesn’t surface a “code 2 = changes applied” because every CI pipeline already knows the previous state via git. Use --dry-run for the “did anything change?” check.

​
Common errors

  • crew "code-review" already exists — drop --strict to update in place, or pass --replace to recreate.
  • aborted: destructive plan requires confirmation (pass --yes) — apply saw a - line in the plan and stdin isn’t a TTY. Pass -y/--yes in CI, or run interactively.
  • invalid services_json: services["xyz"]: name must be a DNS label — service names must be valid RFC 1035 DNS labels (1–63 chars, lowercase letters/digits/-, starting with a letter and ending with letter or digit) since they become bridge-network DNS aliases.
  • skill "X" references unknown credential env "Y" — every env_refs: entry must point at a credential declared in the same manifest (in the crew or at workspace scope).

​
Next step after apply

When the manifest declares spec.devcontainer on any crew, apply prints a hint at the end: 
Next: build crew containers with:
  crewship crew provision code-review
  crewship crew provision triage
The original design auto-provisioned containers, but the apply CLI had already exited by the time provisioning streamed progress — so we surface the chained command instead of hiding it behind a flag. Run the printed line(s) to actually pull images and start the bridge network.

​
See also