Coordination

Distributed locks and polling primitives. Each function lists its parameters, defaults and return value.

Lock Namespace

Distributed mutex primitives. Acquire a named lock from a shared store so concurrent workflow runs serialize on a resource.

Two backends:

postgres — lease table with token-checked release/refresh. Auto-creates the lease table on first use.
dragonfly — Redis-compatible SET NX EX + Lua check-and-act.

Scope: Network

Functions

Function	Description
`lock.acquire()`	Take a lock; returns a token used for subsequent calls
`lock.refresh()`	Extend the lease on an already-held lock
`lock.release()`	Drop a lock previously held under (key, token)
`lock.peek()`	Inspect the current holder without modifying state

Token semantics

Acquire returns an opaque token (a random UUID). The token must be supplied to lock.refresh and lock.release; without a matching token, neither operation will modify the lease.

The token only proves ownership at release time. It is not a monotonic fencing token — workflows that need fencing-grade verification against a downstream resource (e.g. preventing a stale lock holder from writing to a shared bucket) must build that on top of this primitive.

Common Parameters

All four functions accept these parameters for backend selection.

Parameter	Type	Default	Description
`backend`	string	`"postgres"`	`"postgres"` or `"dragonfly"`
`dsn`	string	—	Postgres DSN (`postgres://...`) or Redis URL (`redis://...`) — required
`table`	string	`"kis_locks"`	Postgres lease table name (ignored for dragonfly)
`key`	string	—	Lock key — required for all ops

lock.acquire()

Take a distributed lock under the given key.

Parameters

In addition to the common params above:

Parameter	Type	Default	Description
`ttl`	int or string	—	Lease duration — required (`"5m"` or integer seconds)
`wait`	int or string	`0`	How long to block-and-retry before giving up. Default `0` = fail fast
`owner`	string	—	Optional metadata stamped on the lease (visible to `peek`)

Returns

Field	Type	Description
`success`	bool	Mirrors `acquired`
`acquired`	bool	Whether the lock was taken
`attempts`	int	Number of acquire calls before success or wait expiry
`key`	string	Echoes the requested key
`token`	string	Opaque ownership token (present only on success)
`expiresAt`	string	RFC3339 timestamp when the lease will expire
`error`	string	Failure reason when `success` is `false`

Examples

// Fail-fast acquire
let r = lock.acquire({
  backend: "postgres",
  dsn: PG_DSN,
  key: "deploy/prod",
  ttl: "10m"
})
if (!r.acquired) {
  log("someone else is deploying right now")
  return
}

// Block up to 30s for the lock
let r = lock.acquire({
  backend: "dragonfly",
  dsn: "redis://dragonfly.internal:6379/0",
  key: "certs/rotation",
  ttl: "5m",
  wait: "30s",
  owner: "rotation-bot@" + Date.now()
})

lock.refresh()

Extend the lease on an already-held lock.

Parameters

In addition to the common params:

Parameter	Type	Description
`token`	string	Token from the matching `lock.acquire()` call (required)
`ttl`	int or string	New lease duration (required)

Returns

Field	Type	Description
`success`	bool	Mirrors `refreshed`
`refreshed`	bool	Whether the lease was extended. `false` when the (key, token) pair doesn’t own a live lease
`expiresAt`	string	New RFC3339 expiry on success

Example

// Hold a lock for an extra 2 minutes during a long migration
lock.refresh({
  backend: "postgres",
  dsn: PG_DSN,
  key: "migration/2026-05-19",
  token: heldLock.token,
  ttl: "2m"
})

lock.release()

Drop the lock if the supplied token still owns it. Releasing with the wrong token is a no-op — released: false, no error.

Parameters

In addition to the common params:

Parameter	Type	Description
`token`	string	Token from the matching `lock.acquire()` call (required)

Returns

Field	Type	Description
`success`	bool	Mirrors `released`
`released`	bool	Whether the token still owned a live lease

Example

lock.release({
  backend: "postgres",
  dsn: PG_DSN,
  key: "deploy/prod",
  token: heldLock.token
})

lock.peek()

Inspect the current holder of a key without modifying state.

Returns

Field	Type	Description
`success`	bool	Whether the peek completed (`true` even when the lock isn’t held)
`held`	bool	Whether a live lease exists
`token`	string	Current holder’s token (when `held: true`)
`owner`	string	Current holder’s owner metadata (when set on acquire)
`expiresAt`	string	RFC3339 expiry of the current lease

Example

let peek = lock.peek({
  backend: "dragonfly",
  dsn: "redis://dragonfly.internal:6379/0",
  key: "nightly-report"
})
if (peek.held) {
  log("nightly report already running, owner=" + peek.owner)
}

Full lifecycle in one example

const dsn = "postgres://app:[email protected]:5432/locks?sslmode=disable"

// Acquire — block up to 30 seconds
let held = lock.acquire({
  backend: "postgres",
  dsn: dsn,
  key: "deploy/prod",
  ttl: "10m",
  wait: "30s",
  owner: "deploy-" + Date.now()
})
if (!held.acquired) {
  throw "could not get deploy lock"
}

try {
  // ... do work ...

  // Halfway through, extend the lease
  lock.refresh({
    backend: "postgres",
    dsn: dsn,
    key: "deploy/prod",
    token: held.token,
    ttl: "10m"
  })

  // ... finish work ...
} finally {
  lock.release({
    backend: "postgres",
    dsn: dsn,
    key: "deploy/prod",
    token: held.token
  })
}

Backend behaviour notes

Postgres

Lease table is auto-created (CREATE TABLE IF NOT EXISTS) with an index on expires_at.
Expired leases are stealable: a fresh acquire whose WHERE clause sees expires_at < NOW() will steal the slot. There is no separate garbage-collection job.
The lock client uses a small connection pool (5 open, 2 idle) shared per-DSN across the process.
Table name is validated against [A-Za-z_][A-Za-z0-9_]*.

Dragonfly

Lock value is encoded as "<token>|<owner>" so peek returns the owner in a single GET.
release and refresh use Lua to fold the “is this still my lock?” check and the DEL/PEXPIRE into one atomic step. The same scripts work unchanged against real Dragonfly.
The Redis client is shared per-URL across the process.

Wait Namespace

Polling primitives — block until a runtime condition becomes true.

Today only wait.http is implemented. wait.tcp, wait.dns, wait.exec, wait.file, and wait.db are planned and will land in this namespace without breaking the existing API.

Scope: Network

Functions

Function	Description
`wait.http()`	Poll an HTTP endpoint until the response satisfies the configured criteria

wait.http()

Poll a URL repeatedly until the response satisfies every configured matcher, or the timeout elapses, or the calling context is cancelled.

Parameters

Parameter	Type	Default	Description
`url`	string	—	Target URL (required)
`method`	string	`"GET"`	HTTP method
`headers`	map	—	Request headers — sent on every poll
`body`	string	—	Request body — reused on every poll
`status`	int or [int]	`200`	Acceptable HTTP status code(s)
`bodyMatch`	string	—	Regex the response body must match
`bodyContains`	string	—	Substring the response body must contain
`headerMatch`	map	—	Per-header regex constraints (header name → regex)
`interval`	int or string	`5s`	Time between polls (`"5s"` or integer seconds)
`timeout`	int or string	`5m`	Total timeout
`initialDelay`	int or string	`0`	Delay before the first poll
`insecureTLS`	bool	`false`	Skip TLS certificate verification
`expectFailure`	bool	`false`	Invert: succeed when the URL stops responding

Returns

Field	Type	Description
`success`	bool	Whether the wait condition was met
`attempts`	int	Polls performed
`elapsedMs`	int	Total elapsed milliseconds
`lastStatus`	int	Status of the final poll (populated on timeout too)
`lastBody`	string	Body of the final poll
`lastHeaders`	map	Headers of the final poll
`error`	string	Failure reason when `success` is `false`

Notes

expectFailure: true is the inverse mode. Connection errors (refused, DNS failure, TLS rejection) count as success. A 2xx still counts as “service is up — keep waiting.” Use it to gate on shutdown.
bodyMatch is regexp.MatchString (Go’s RE2 dialect). bodyContains is a literal substring test — cheaper and easier to write when you don’t need regex.
headerMatch entries combine with AND — every named header must match its regex.
interval caps each individual request as well (the HTTP client’s per-request timeout). A response that takes longer than the interval is treated as a non-match for that attempt.
Last response is captured even on timeout — lastStatus, lastBody, and lastHeaders reflect the final poll attempt, so you can introspect why the condition never became true.

Examples

Block until a service comes up

let r = wait.http({
  url: "http://localhost:8080/healthz",
  interval: "2s",
  timeout: "90s"
})
if (!r.success) {
  throw "service never came up: " + r.error
}

Long-running job polling

let r = wait.http({
  url: "https://api.example.com/jobs/" + jobId,
  headers: { Authorization: "Bearer " + token },
  bodyContains: '"status":"done"',
  interval: "5s",
  timeout: "30m"
})
log("job took " + r.elapsedMs + "ms (" + r.attempts + " polls)")

Version gate via regex

wait.http({
  url: "https://api.example.com/version",
  bodyMatch: "\"version\":\"2\\.\\d+\\.\\d+\"",
  interval: "10s",
  timeout: "10m"
})

Status-list (accept any 2xx)

wait.http({
  url: "https://api.example.com/health",
  status: [200, 201, 202, 204],
  interval: "3s",
  timeout: "2m"
})

Wait for shutdown (invert)

wait.http({
  url: "http://localhost:8080/healthz",
  expectFailure: true,
  interval: "1s",
  timeout: "30s"
})

Header gate

wait.http({
  url: "https://api.example.com/health",
  headerMatch: {
    "X-Version": "^v2\\.",
    "X-Mode":    "^production$"
  },
  interval: "5s",
  timeout: "5m"
})

Read the captured last response on timeout

let r = wait.http({
  url: "https://api.example.com/state",
  bodyContains: '"ready":true',
  timeout: "2m"
})
if (!r.success) {
  log("gave up after " + r.attempts + " polls; last status=" + r.lastStatus)
  log("last body: " + r.lastBody)
}

POST polling with a body

wait.http({
  method: "POST",
  url: "https://api.example.com/check",
  body: '{"region":"us-east-1"}',
  headers: { "Content-Type": "application/json" },
  bodyContains: '"ok":true',
  interval: "10s",
  timeout: "5m"
})

Cron Namespace

Scheduled job management functions. Manages recurring and one-time jobs with YAML-based storage and OS scheduler integration. Cross-platform support for crontab (Linux), launchd (macOS), and Task Scheduler (Windows).

Scope: System

Functions

Function	Description
`cron.add()`	Add a recurring scheduled job
`cron.once()`	Schedule a one-time job
`cron.remove()`	Remove a job
`cron.list()`	List all managed jobs
`cron.show()`	Show details of a specific job
`cron.exec()`	Execute a job in foreground
`cron.run()`	Run a job in background
`cron.logs()`	View job log output
`cron.history()`	View job execution history
`cron.sync()`	Sync between YAML store and OS scheduler

cron.add()

Add a recurring scheduled job.

Parameters

Parameter	Type	Default	Description
`name`	string	—	Job name (required)
`command`	string	—	Command to execute (required)
`schedule`	string	—	Schedule expression (required)
`dir`	string	—	Working directory
`shell`	string	`/bin/sh`	Shell to use
`env`	map	—	Environment variables
`timeout`	string	—	Job timeout (`30m`, `1h`)
`overlap`	string	—	Concurrent execution: `skip`, `queue`, `allow`
`enabled`	bool	`true`	Whether job is active

Schedule accepts human-friendly expressions (daily at 2am, every 5 minutes, weekly on monday at 9am) or raw cron syntax (cron */5 * * * *).

Returns

Field	Type	Description
`success`	bool	Whether the job was added
`job`	map	Job details (name, schedule, cron, command, enabled, etc.)
`error`	string	Error message if failed

Examples

// Add a daily backup job
let result = cron.add({
  name: "daily-backup",
  command: "/opt/scripts/backup.sh",
  schedule: "daily at 2am",
  dir: "/opt/backup",
  timeout: "1h",
  env: { BACKUP_DIR: "/mnt/backups" }
})
log("Job created: " + result.job.name)

// Add with raw cron expression
cron.add({
  name: "health-check",
  command: "curl -sf http://localhost:8080/health",
  schedule: "cron */5 * * * *",
  timeout: "30s"
})

// Add weekly report
cron.add({
  name: "weekly-report",
  command: "/opt/scripts/report.sh",
  schedule: "weekly on monday at 9am",
  env: { REPORT_EMAIL: "[email protected]" }
})

cron.once()

Schedule a one-time job execution.

Parameters

Parameter	Type	Default	Description
`name`	string	—	Job name (required)
`command`	string	—	Command to execute (required)
`time`	string	—	When to run: `now`, `in 5 minutes`, `today at 3pm` (required)
`dir`	string	—	Working directory
`shell`	string	`/bin/sh`	Shell to use
`env`	map	—	Environment variables
`timeout`	string	—	Job timeout

Returns

Field	Type	Description
`success`	bool	Whether the job was scheduled
`job`	map	Job details
`error`	string	Error message if failed

Examples

// Run immediately
cron.once({
  name: "db-migrate",
  command: "/opt/scripts/migrate.sh",
  time: "now"
})

// Schedule for later
cron.once({
  name: "deploy-v2",
  command: "/opt/scripts/deploy.sh --version v2.0.0",
  time: "today at 11pm",
  dir: "/opt/app"
})

// Schedule in relative time
cron.once({
  name: "cleanup",
  command: "/opt/scripts/cleanup.sh",
  time: "in 30 minutes"
})

cron.remove()

Remove a scheduled job.

Parameters

Parameter	Type	Default	Description
Input	string or map	—	Job name string, or map with `name` key (required)

Returns

Field	Type	Description
`success`	bool	Whether the job was removed
`error`	string	Error message if failed

Examples

// Remove by name string
cron.remove("health-check")

// Remove with map
cron.remove({ name: "old-backup" })

cron.list()

List all managed jobs.

Parameters

Parameter	Type	Default	Description
Input	nil or map	—	Optional map with `data_dir`

Returns

Field	Type	Description
`success`	bool	Whether the listing succeeded
`jobs`	array	Array of job objects
`error`	string	Error message if failed

Each job object contains:

Field	Type	Description
`name`	string	Job name
`schedule`	string	Human-friendly schedule
`cron`	string	Cron expression
`command`	string	Command to execute
`enabled`	bool	Whether the job is active
`created`	string	Creation timestamp (ISO 8601)
`updated`	string	Last update timestamp (ISO 8601)

Examples

// List all jobs
let result = cron.list()
for (let job of result.jobs) {
  let status = job.enabled ? "enabled" : "disabled"
  log(job.name + " [" + status + "] — " + job.schedule)
}

// Count enabled jobs
let result = cron.list()
let enabled = result.jobs.filter(j => j.enabled).length
log("Enabled jobs: " + enabled + "/" + result.jobs.length)

cron.show()

Show details of a specific job.

Parameters

Parameter	Type	Default	Description
Input	string or map	—	Job name string, or map with `name` key (required)

Returns

Field	Type	Description
`success`	bool	Whether the lookup succeeded
`job`	map	Full job details
`error`	string	Error message if failed

Examples

// Show by name
let result = cron.show("daily-backup")
log("Schedule: " + result.job.schedule)
log("Cron: " + result.job.cron)
log("Command: " + result.job.command)
log("Enabled: " + result.job.enabled)

// Show with map
let result = cron.show({ name: "health-check" })
log("Timeout: " + result.job.timeout)

cron.exec()

Execute a job immediately in the foreground. Waits for completion and returns output.

Parameters

Parameter	Type	Default	Description
Input	string or map	—	Job name string, or map with `name` key (required)

Returns

Field	Type	Description
`success`	bool	Whether execution succeeded
`output`	string	Command output
`exit_code`	int	Process exit code
`error`	string	Error message if failed

Examples

// Execute in foreground
let result = cron.exec("daily-backup")
if (result.success) {
  log("Output: " + result.output)
  log("Exit code: " + result.exit_code)
} else {
  log("Failed: " + result.error)
}

cron.run()

Run a job in the background. Returns immediately without waiting for completion.

Parameters

Parameter	Type	Default	Description
Input	string or map	—	Job name string, or map with `name` key (required)

Returns

Field	Type	Description
`success`	bool	Whether the job was started
`output`	string	Startup output
`error`	string	Error message if failed

Examples

// Run in background
let result = cron.run("daily-backup")
if (result.success) {
  log("Job started in background")
}

cron.logs()

View job log output.

Parameters

Parameter	Type	Default	Description
Input	string or map	—	Job name string, or map with options (required)
`name`	string	—	Job name (required)
`lines`	int	`50`	Number of log lines to return

Returns

Field	Type	Description
`success`	bool	Whether the logs were retrieved
`logs`	string	Log content
`error`	string	Error message if failed

Examples

// View last 50 lines (default)
let result = cron.logs("daily-backup")
log(result.logs)

// View last 100 lines
let result = cron.logs({ name: "daily-backup", lines: 100 })
log(result.logs)

cron.history()

View job execution history with timestamps, duration, and exit codes.

Parameters

Parameter	Type	Default	Description
Input	string or map	—	Job name string, or map with options (required)
`name`	string	—	Job name (required)
`lines`	int	`50`	Number of history entries

Returns

Field	Type	Description
`success`	bool	Whether the history was retrieved
`history`	array	Array of history entries
`error`	string	Error message if failed

Each history entry contains:

Field	Type	Description
`job`	string	Job name
`started`	string	Start timestamp (ISO 8601)
`finished`	string	Finish timestamp (ISO 8601)
`duration`	string	Execution duration
`exit_code`	int	Process exit code
`trigger`	string	What triggered the execution

Examples

// View recent history
let result = cron.history("daily-backup")
for (let entry of result.history) {
  let status = entry.exit_code === 0 ? "OK" : "FAILED"
  log(entry.started + " — " + entry.duration + " — " + status)
}

// View last 20 entries
let result = cron.history({ name: "health-check", lines: 20 })
let failures = result.history.filter(e => e.exit_code !== 0)
log("Failures: " + failures.length + "/" + result.history.length)

cron.sync()

Sync between the YAML job store and the OS scheduler (crontab, launchd, or Task Scheduler).

Parameters

Parameter	Type	Default	Description
`direction`	string	`"both"`	Sync direction: `to-os`, `from-os`, `both`
`dry_run`	bool	`false`	Preview changes without applying

Returns

Field	Type	Description
`success`	bool	Whether the sync succeeded
`changes`	array	Array of change objects
`error`	string	Error message if failed

Each change object contains:

Field	Type	Description
`action`	string	Change action (add, remove, update)
`name`	string	Job name
`detail`	string	Description of the change

Examples

// Sync YAML to OS scheduler
let result = cron.sync({ direction: "to-os" })
for (let change of result.changes) {
  log(change.action + ": " + change.name + " — " + change.detail)
}

// Preview changes (dry run)
let result = cron.sync({ direction: "both", dry_run: true })
log("Pending changes: " + result.changes.length)
for (let change of result.changes) {
  log("  [" + change.action + "] " + change.name)
}

// Sync from OS to YAML
cron.sync({ direction: "from-os" })

Full Workflow Example

// Complete job lifecycle: create, verify, execute, check logs, clean up
let jobName = "nightly-backup"

// Create the job
let added = cron.add({
  name: jobName,
  command: "/opt/scripts/backup.sh --full",
  schedule: "daily at 2am",
  dir: "/opt/backup",
  timeout: "2h",
  env: {
    BACKUP_TARGET: "/mnt/backups",
    RETENTION_DAYS: "30"
  }
})
log("Created job: " + added.job.name)

// Verify it was created
let details = cron.show(jobName)
log("Schedule: " + details.job.schedule)
log("Cron expression: " + details.job.cron)

// Execute immediately to test
let execResult = cron.exec(jobName)
log("Test run exit code: " + execResult.exit_code)

// Check logs
let logs = cron.logs({ name: jobName, lines: 20 })
log("Output: " + logs.logs)

// Sync to OS scheduler
let syncResult = cron.sync({ direction: "to-os" })
log("Synced " + syncResult.changes.length + " changes to OS")

// List all jobs
let allJobs = cron.list()
log("Total managed jobs: " + allJobs.jobs.length)

Port Namespace

TCP/UDP port management functions.

Scope: System

Functions

Function	Description
`port.check()`	Check if a port is free
`port.find()`	Find the first free port in a range
`port.list()`	List processes using a port
`port.kill()`	Kill all processes on a port

port.check()

Check if a TCP/UDP port is free. Uses fuser on Linux.

Parameters

Parameter	Type	Default	Description
Input	int or map	—	Port number, or map with options (required)
`port`	int	—	Target port number (required)
`protocol`	string	`"tcp"`	Protocol: `"tcp"` or `"udp"`

Returns

Field	Type	Description
`success`	bool	Whether the check completed
`free`	bool	Whether the port is free
`error`	string	Error message if failed

Examples

// Simple check with port number
let result = port.check(8080)
if (result.free) {
  log("Port 8080 is available")
} else {
  log("Port 8080 is in use")
}

// Check UDP port
let result = port.check({ port: 5353, protocol: "udp" })
log("UDP 5353 free: " + result.free)

port.find()

Find the first free port in a range. Scans from startport to endport in steps of increment, skipping ports below minport.

Parameters

Parameter	Type	Default	Description
`startport`	int	`3000`	Range start
`endport`	int	`65000`	Range end
`increment`	int	`1000`	Step size
`minport`	int	`10000`	Skip ports below this value
`protocol`	string	`"tcp"`	Protocol: `"tcp"` or `"udp"`

Returns

Field	Type	Description
`success`	bool	Whether a free port was found
`port`	int	The free port number
`error`	string	Error message if failed

Examples

// Find free port with defaults
let result = port.find({})
log("Free port: " + result.port)

// Find in a specific range
let result = port.find({
  startport: 10000,
  endport: 60000,
  increment: 100
})
log("Free port: " + result.port)

// Find with minimum port
let result = port.find({
  startport: 3000,
  endport: 65000,
  increment: 1000,
  minport: 20000
})
if (result.success) {
  log("Found port: " + result.port)
} else {
  log("No free port found in range")
}

port.list()

List processes using a specific port.

Parameters

Parameter	Type	Default	Description
Input	int or map	—	Port number, or map with options (required)
`port`	int	—	Target port number (required)
`protocol`	string	`"tcp"`	Protocol: `"tcp"` or `"udp"`

Returns

Field	Type	Description
`success`	bool	Whether the listing succeeded
`processes`	array	Array of process objects
`error`	string	Error message if failed

Each process object contains:

Field	Type	Description
`pid`	string	Process ID
`user`	string	Process owner
`command`	string	Command name

Examples

// List processes on port 8080
let result = port.list(8080)
for (let p of result.processes) {
  log(p.pid + " " + p.user + " " + p.command)
}

// List with protocol
let result = port.list({ port: 53, protocol: "udp" })
if (result.processes.length === 0) {
  log("No processes on UDP port 53")
} else {
  log("Found " + result.processes.length + " processes")
}

port.kill()

Kill all processes using a port. Sends the specified signal to all processes.

Parameters

Parameter	Type	Default	Description
Input	int or map	—	Port number, or map with options (required)
`port`	int	—	Target port number (required)
`protocol`	string	`"tcp"`	Protocol: `"tcp"` or `"udp"`
`signal`	string	`"KILL"`	Signal to send (`KILL`, `TERM`, `HUP`, etc.)

Returns

Field	Type	Description
`success`	bool	Whether the kill succeeded
`free`	bool	Whether the port is now free
`error`	string	Error message if failed

Examples

// Kill with default signal (KILL)
let result = port.kill(8080)
log("Port free: " + result.free)

// Graceful termination
port.kill({ port: 8080, signal: "TERM" })

// Kill processes on UDP port
port.kill({ port: 5353, protocol: "udp", signal: "TERM" })

Full Workflow Example

// Port management workflow: check, list, kill, verify
let targetPort = 8080

// Check if port is in use
let check = port.check(targetPort)
if (!check.free) {
  // List what's using it
  let procs = port.list(targetPort)
  log("Port " + targetPort + " is in use by:")
  for (let p of procs.processes) {
    log("  PID " + p.pid + ": " + p.command + " (" + p.user + ")")
  }

  // Graceful kill
  port.kill({ port: targetPort, signal: "TERM" })

  // Verify it's free
  let verify = port.check(targetPort)
  if (verify.free) {
    log("Port " + targetPort + " is now free")
  } else {
    // Force kill
    port.kill(targetPort)
  }
} else {
  log("Port " + targetPort + " is available")
}

User Namespace

OS user management functions.

Scope: System

Functions

Function	Description
`user.check()`	Check if an OS user exists
`user.create()`	Create a new OS user
`user.delete()`	Delete an OS user
`user.modify()`	Modify user properties
`user.passwd()`	Set or change a user password

user.check()

Check if an OS user exists. Returns user details (UID, GID, home directory) when found.

Parameters

Parameter	Type	Default	Description
Input	string or map	—	Username string, or map with `username` key (required)

Returns

Field	Type	Description
`success`	bool	Whether the check completed
`exists`	bool	Whether the user exists
`uid`	string	User’s numeric UID
`gid`	string	User’s numeric GID
`homedir`	string	User’s home directory
`error`	string	Error message if failed

Examples

// Check with username string
let result = user.check("deploybot")
if (result.exists) {
  log("User found — UID: " + result.uid + ", Home: " + result.homedir)
} else {
  log("User does not exist")
}

// Check with map
let result = user.check({ username: "appuser" })
log("Exists: " + result.exists)

user.create()

Create a new OS user. Uses useradd on Linux.

Parameters

Parameter	Type	Default	Description
Input	string or map	—	Username string, or map with options (required)
`username`	string	—	Target username (required)
`groupname`	string	—	Primary group name
`shell`	string	`/bin/bash`	Login shell
`home`	string	—	Home directory path
`groups`	array	—	Supplementary groups
`createhome`	bool	`true`	Create home directory
`system`	bool	`false`	Create as system account

Returns

Field	Type	Description
`success`	bool	Whether the user was created
`error`	string	Error message if failed

Examples

// Simple create with username string
user.create("deploybot")

// Create with primary group and supplementary groups
user.create({
  username: "deploybot",
  groupname: "deploy",
  groups: ["docker", "sudo"],
  shell: "/bin/bash"
})

// Create a system account
user.create({
  username: "myservice",
  system: true,
  createhome: false
})

// Create with custom home directory
user.create({
  username: "webapp",
  home: "/opt/webapp",
  groupname: "www-data"
})

user.delete()

Delete an OS user. Uses userdel on Linux.

Parameters

Parameter	Type	Default	Description
Input	string or map	—	Username string, or map with options (required)
`username`	string	—	Target username (required)
`removehome`	bool	`false`	Remove home directory on deletion

Returns

Field	Type	Description
`success`	bool	Whether the user was deleted
`error`	string	Error message if failed

Examples

// Simple delete
user.delete("olduser")

// Delete and remove home directory
user.delete({ username: "olduser", removehome: true })

user.modify()

Modify OS user properties. Uses usermod on Linux.

Parameters

Parameter	Type	Default	Description
`username`	string	—	Target username (required)
`groupname`	string	—	New primary group
`shell`	string	—	New login shell
`home`	string	—	New home directory
`groups`	array	—	New supplementary groups

Returns

Field	Type	Description
`success`	bool	Whether the modification succeeded
`error`	string	Error message if failed

Examples

// Add user to more groups
user.modify({
  username: "deploybot",
  groups: ["docker", "sudo", "adm"]
})

// Change shell
user.modify({
  username: "deploybot",
  shell: "/bin/zsh"
})

// Change primary group and home
user.modify({
  username: "webapp",
  groupname: "www-data",
  home: "/var/www/webapp"
})

user.passwd()

Set or change an OS user’s password. Uses chpasswd on Linux.

Parameters

Parameter	Type	Default	Description
`username`	string	—	Target username (required)
`password`	string	—	New password in plain text (required)

Returns

Field	Type	Description
`success`	bool	Whether the password was set
`error`	string	Error message if failed

Examples

// Set password
user.passwd({
  username: "deploybot",
  password: "secure-password-123"
})

Full Workflow Example

// Complete user provisioning workflow
let username = "deploybot"

// Check if user already exists
let result = user.check(username)
if (!result.exists) {
  // Create user with groups
  let created = user.create({
    username: username,
    groupname: "deploy",
    groups: ["docker", "sudo"],
    shell: "/bin/bash"
  })

  if (created.success) {
    // Set initial password
    user.passwd({
      username: username,
      password: "initial-password"
    })
    log("User " + username + " created successfully")
  }
} else {
  log("User " + username + " already exists (UID: " + result.uid + ")")

  // Ensure correct groups
  user.modify({
    username: username,
    groups: ["docker", "sudo", "adm"]
  })
}