Skip to content
Documentation
State Modules
cmd

cmd

Executes an arbitrary shell command via /bin/sh, gated by an idempotency guard (creates, onlyif, or unless). The mandatory guard keeps the declaration idempotent: once the command’s work is done the guard flips to skip and re-applying reports no change.

Category: System & core

States

StateMeaning
runRun command through /bin/sh unless its guard (creates/onlyif/unless) says the work is already done.

Parameters

ParameterTypeRequiredDescription
commandstringyesThe shell command to execute via /bin/sh -c.
createsstringAbsolute path; skip the command if this path already exists. Acts as the idempotency guard.
onlyifstringGuard command; run command only if this exits zero.
unlessstringGuard command; run command only if this exits non-zero.
cwdstringWorking directory the command runs in.
envmapEnvironment variables (string keys to string values) added to the command’s environment.
timeout_secondsintKill the command after this many seconds. Range [0, 3600]. Default: 60.
shellstringShell interpreter. Only /bin/sh is supported in v1.0; alternate shells are v1.x. Default: /bin/sh.

Examples

Run once, guarded by a marker file

creates makes the declaration idempotent: the command is skipped once the path exists.

cmd:
  bootstrap-db:
    state: run
    command: /opt/myapp/bin/init-db && touch /var/lib/myapp/.initialized
    creates: /var/lib/myapp/.initialized

Guard with onlyif and a working directory 

cmd:
  rebuild-cache:
    state: run
    command: make cache
    cwd: /opt/myapp
    onlyif: test -f /opt/myapp/cache.dirty
    timeout_seconds: 300

Run after a package install, with env

The require requisite orders this command after the package is present.

cmd:
  migrate:
    state: run
    command: myapp migrate
    unless: myapp migrate --check
    env:
      MYAPP_ENV: production
    require:
      - package: myapp

Notes

  • Linux and macOS only; the module is /bin/sh-based, so Windows / cmd.exe is v1.x.
  • state: run requires at least one guard (creates / onlyif / unless) for idempotency; use onlyif: /bin/true to opt into always-run.
  • creates must be an absolute path.
  • A successful Apply always counts as a change; the engine only invokes Apply when Check reports the guards say “run”.
  • Out of scope for v0.1: runas (run as another user), non-POSIX shells, sandboxing (seccomp / namespaces), and command-policy integration.
file