CLI

The depends CLI manages dependency graphs defined in depends.yml files. It supports local development (depends serve), hosted (Operating Modes) or self-hosted servers, state updates, health checks (meta.checks), visualization, events, usage stats, and admin tasks. Graphs define nodes, edges (depends_on), labels, defaults, metadata, and notifications.

Run depends without arguments for usage.

Usage

depends — CLI for depends.cc

Usage:
  depends serve [-p <port>]                   Run the server locally (default: 3000)
  depends signup <email> <lak_...>             Sign up (token emailed to you)
  depends init                                Create a depends.yml in the current directory
  depends push [--prune]                      Upload depends.yml (auto-creates namespace)
  depends pull                                Download graph as depends.yml
  depends show                                Print the current spec (YAML) without saving
  depends status [<node-id>]                  Show node states (color-coded)
  depends set [<namespace>/]<node-id> <state> Set a node's state (green/yellow/red)
  depends graph                               Print dependency tree
  depends events [<ns/node>]                  Show recent state changes
  depends validate                            Check depends.yml for errors
  depends delete                              Delete a namespace and all its data
  depends usage                               Show usage stats for current billing period
  depends check [--dry-run]                   Run meta.checks and update state
  depends diff                                Show what would change on push
  depends update                              Update to the latest version
  depends admin tokens                        List all tokens (server admin)

Options:
  -n, --namespace <ns>    Override namespace
  -p <port>               Port for serve (default: 3000)
  --json                  Output as JSON (with status, events)
  --limit <n>             Number of events to show (default: 20)
  --reason <text>         Reason for state change (with set)
  --solution <text>       Recommended fix (with set)
  --prune                 Remove nodes not in YAML (with push)
  --dry-run               Simulate check without state updates
  -h, --help              Show help

Configuration

CLI loads from ~/.config/depends/config.yml (overridable by DEPENDS_CONFIG) and environment variables (higher precedence).

# ~/.config/depends/config.yml
default_namespace: my-project
token: abc123def456...
api_url: https://depends.cc/v1  # Optional; defaults to hosted or local

Environment variables:

No token → local mode (token: "dep_local", api_url: "http://localhost:3000/v1").

Namespace resolution (required for most commands):

  1. -n/--namespace
  2. depends.yml namespace (read raw, no substitution)
  3. default_namespace from config/env
  4. Error

depends.yml Format

Declarative YAML for graphs/notifications. Supports env substitution (${VAR}, ${VAR:-default}) in CLI before upload (unsubstituted vars without default → error).

namespace: my-project  # Required

nodes:  # Optional map<id, spec>
  database:
    label: PostgreSQL  # Display name
    default_state: green  # Initial state (green/yellow/red); defaults yellow
    meta:  # Arbitrary JSON; e.g., checks for `depends check`
      checks:
        - url: https://db.example.com/health
          grep: "ok"  # String/array; HTTP GET, non-2xx/missing → failure
    depends_on:  # Directed edges (this → deps); cycles rejected on push
      - cache

notifications:  # Optional map<id, spec>; see [notifications.md]
  slack:
    watch: "*"  # Node ID or "*"
    on: [red, yellow]  # String/array; "*" all states
    url: https://hooks.slack.com/...
    secret: mysecret  # HMAC-SHA256 (X-Signature)
    email: true  # Send to token owner email
    ack: true  # Suppress after fire (ack_token in payload)
// Cycle detection example (src/cli/commands/validate.ts)
const adjList = new Map<string, string[]>();
// Build from nodes → depends_on
const inDegree = new Map(/* count incoming */);
const queue = [...nodes with indegree 0];
let sorted = 0;
while (queue.length) {
  const node = queue.shift()!;
  sorted++;
  // Reduce indegrees of deps, enqueue 0s
}
if (sorted < totalNodes) throw new Error("Cycle detected");

Commands

Setup

init

Scaffolds depends.yml (fails if exists); namespace from sanitized dir name.

Usage: depends init

serve

Runs local server; creates data/depends.db.

Usage: depends serve [-p ]

signup

Registers hosted account; emails token. Prompts if args missing.

Usage: depends signup [email] [lak_...]

update

git pull && bun install in install dir.

Usage: depends update

Graph Management

push

Substitutes env, uploads YAML (PUT /graph/{ns}); auto-creates ns; optional prune.

Usage: depends push [--prune]

pull

Downloads YAML to depends.yml.

Usage: depends pull

diff

Structural diff local vs remote YAML (nodes, labels, deps); colors new(~ green), pruneable(red), changed(yellow).

Usage: depends diff

show

Prints remote YAML.

Usage: depends show

validate

Local checks: YAML, namespace, cycles, missing deps (warn).

Usage: depends validate

delete

DELETE /namespaces/{ns} (all data).

Usage: depends delete

Inspection

status

Lists nodes (state/effective/label/reason) or single-node details (deps). --json.

Usage: depends status [/] [--json]

graph

Unicode tree: roots first, dependents as children; colors effective state.

Usage: depends graph

events

Recent changes (prev→new states/effective, reason). --json/--limit.

Usage: depends events [/] [--limit ] [--json]

usage

Billing stats (nodes/events/webhooks/emails). --json.

Usage: depends usage [--json]

Updates

set

PUT /state/{ns}/{node}/{state} (green/yellow/red); propagates effective (Graph Computation).

Usage: depends set [/] [--reason ] [--solution ]

check

Parallel HTTP checks (meta.checks: GET+grep); sets green/red + reason. --dry-run.

Usage: depends check [--dry-run]

Admin (Local Server)

Run from server dir (data/depends.db).

admin tokens

Lists tokens (ID/email/linked/created).

Usage: depends admin tokens

Recent changes