Docs — depends.cc

Install the `depends` command

Install

curl -fsSL https://depends.cc/install.sh | sh

Commands

Command	Description
`depends serve [-p <port>]`	Run the server locally (default: 3000)
`depends signup <email>`	Create an account (token emailed to you)
`depends init`	Scaffold a `depends.yml` in the current directory
`depends push [--prune]`	Upload `depends.yml` to the server (auto-creates namespace)
`depends pull`	Download the remote graph into `depends.yml`
`depends status [<ns/node>]`	Show node states (supports `--json`)
`depends set [<ns/>]<node> <state>`	Set state to green, yellow, or red
`depends graph`	Print the dependency tree
`depends events [<ns/node>]`	Show recent state changes (supports `--json`, `--limit`)
`depends usage`	Show usage stats for current billing period
`depends validate`	Check `depends.yml` for errors and cycles
`depends diff`	Show what would change on push
`depends delete [-n <ns>]`	Delete a namespace and all its data
`depends update`	Update to the latest version

Options

Flag	Description
`-n, --namespace <ns>`	Override namespace
`--reason <text>`	Reason for state change (with `set`)
`--solution <text>`	Recommended fix (with `set`)
`--json`	Output as JSON (with `status`, `events`)
`--limit <n>`	Number of events to show (default: 20, with `events`)
`--prune`	Remove nodes not in YAML (with `push`)

Configuration

The depends command resolves config from (highest priority first):

Environment variables: DEPENDS_TOKEN, DEPENDS_NAMESPACE, DEPENDS_API_URL
~/.depends/config.yml — token, default_namespace, api_url
depends.yml in the current directory (for namespace)

If no token is configured, the depends command defaults to local mode (dep_local token against localhost:3000).

depends.yml

The depends.yml file defines your dependency graph as code. Push it with depends push or PUT /v1/graph/:namespace.

Full example

namespace: myproject

nodes:
  database:
    label: PostgreSQL Primary

  cache:
    label: Redis
    ttl: 5m

  api-server:
    label: API Server
    depends_on:
      - database
      - cache
    meta:
      team: backend
      region: eu-west-1

  worker:
    label: Background Worker
    depends_on:
      - api-server

  platform:
    label: Platform Health
    default_state: green
    depends_on:
      - api-server
      - worker

notifications:
  ops-slack:
    url: https://hooks.slack.com/services/T.../B.../xxx
    watch: "*"
    on: red
    secret: my-hmac-secret

  db-alert:
    email: true
    watch: database
    on:
      - red
      - yellow
    ack: true

Node fields

Field	Type	Description
`label`	string	Human-readable name
`depends_on`	string[]	List of node IDs this node depends on. Referenced nodes are auto-created if they don't exist.
`default_state`	string	Initial state for new nodes: `green`, `yellow`, or `red`. Useful for aggregator nodes that only reflect their dependencies — set to `green` so the node is transparent.
`meta`	object	Arbitrary key-value metadata (team, region, etc.)
`ttl`	string	Auto-expire to yellow if no state write within this duration (e.g. `30s`, `5m`, `1h`, `7d`)

State is not set in the YAML — it's set at runtime via the API or the depends command. New nodes default to yellow unless default_state is specified.

Notification fields

Field	Type	Description
`url`	string	Webhook URL to POST to
`email`	boolean	`true` to send to the token owner's email (alternative to `url`)
`watch`	string	Node ID to watch, or `` for all (default: ``)
`on`	string or string[]	Trigger on state: `red`, `yellow`, `green`, or `*` (default: `red`)
`secret`	string	HMAC-SHA256 signing secret for the webhook payload
`ack`	boolean	If true, suppresses after firing until acknowledged via the API

Each rule must have at least one of url or email. Both can be set on the same rule.

Push options

Option	Description
`depends push`	Creates/updates nodes and edges. Existing nodes keep their current state.
`depends push --prune`	Also removes nodes that are not in the YAML file.

API Reference

All API routes are under /v1. Authenticated routes require a Bearer token in the Authorization header.

Authentication

POST /v1/signup

Create a new account. Body: {"email": "you@example.com"}. Your token will be emailed to you.

curl -s -X POST https://depends.cc/v1/signup \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com"}'

Namespaces

POST /v1/namespaces

Create a namespace. Requires token auth (no namespace needed).

curl -s -X POST https://depends.cc/v1/namespaces \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id": "myproject"}'

DELETE /v1/namespaces/:namespace

Delete a namespace and all its nodes, edges, events, and notification rules.

Nodes

GET /v1/nodes/:namespace

List all nodes in a namespace.

GET /v1/nodes/:namespace/:nodeId

Get a single node with its state, effective state, reason, solution, and edges.

PUT /v1/nodes/:namespace/:nodeId

Create or update a node. Body (JSON): label, depends_on, meta, ttl.

DELETE /v1/nodes/:namespace/:nodeId

Delete a node and its edges.

State

PUT /v1/state/:namespace/:nodeId/:state

Set a node's state to green, yellow, or red. Auto-creates the node if it doesn't exist.

Optional headers:

X-Depends-Reason — why is this state being set?
X-Depends-Solution — what should be done to resolve it?

curl -X PUT https://depends.cc/v1/state/myproject/database/red \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Depends-Reason: disk full on /var/data" \
  -H "X-Depends-Solution: Clear /var/log, expand volume"

Events

GET /v1/events/:namespace

GET /v1/events/:namespace/:nodeId

List state change events. Query params: limit, since, until.

Graph

GET /v1/graph/:namespace

Get the full dependency graph. Add ?format=yaml for YAML output.

PUT /v1/graph/:namespace

Upload a YAML graph definition. Add ?prune=true to remove nodes not in the YAML.

Content-Type: application/yaml

GET /v1/graph/:namespace/:nodeId

Get the subgraph for a single node.

GET /v1/graph/:namespace/:nodeId/upstream

GET /v1/graph/:namespace/:nodeId/downstream

Get transitive upstream dependencies or downstream dependents.

Notifications

GET /v1/notifications/:namespace

List notification rules.

PUT /v1/notifications/:namespace

Create or update a notification rule. Body (JSON):

id — rule identifier
url — webhook URL
email — true to email the token owner (alternative to url)
watch — node ID or * for all (default: *)
on — trigger state: red, green, yellow, comma-separated, or * (default: red)
secret — HMAC-SHA256 signing secret
ack — if true, suppresses after firing until acknowledged

DELETE /v1/notifications/:namespace/:ruleId

Delete a notification rule.

POST /v1/notifications/:namespace/:ruleId/ack

Acknowledge (un-suppress) a notification rule so it can fire again.

Usage

GET /v1/usage/:namespace

Get current usage stats and plan limits for a namespace.

Status Page

Browser-friendly status view

GET /ns/:namespace

View node status in plain text. Uses HTTP Basic Auth — enter any username (e.g. your email) and your dep_... token as the password. One login covers all your namespaces.

GET /ns/:namespace.json

Same data as JSON. Identical output to GET /v1/nodes/:namespace.

GET /ns/:namespace.yaml

Full graph as YAML — nodes, edges, and notification rules. Same format as depends.yml.

GET /ns/:namespace/:nodeId

Single node detail in plain text. Shows state, label, reason, solution, and edges.

GET /ns/:namespace/:nodeId.json

Single node detail as JSON. Identical output to GET /v1/nodes/:namespace/:nodeId.

# All nodes (plain text)
curl -u me@example.com:dep_yourtoken https://depends.cc/ns/myproject

# All nodes (JSON)
curl -u me@example.com:dep_yourtoken https://depends.cc/ns/myproject.json

# Full graph (YAML)
curl -u me@example.com:dep_yourtoken https://depends.cc/ns/myproject.yaml

# Single node
curl -u me@example.com:dep_yourtoken https://depends.cc/ns/myproject/database
curl -u me@example.com:dep_yourtoken https://depends.cc/ns/myproject/database.json

In a browser, visiting /ns/myproject will prompt for credentials.

Install the depends command