---
title: "Nodes & Connections"
canonical: https://trickest.com/docs/developer-tools/cli/nodes
description: "Add, configure, label, connect, disconnect, and distribute nodes in the active workflow."
---

# Nodes & Connections

Nodes are the building blocks of a workflow — tools, scripts, modules, and
primitives. The `node`, `connect`, and `disconnect` commands edit the structure of
your **active workflow**.

<Note>
Every command on this page operates on the **active workflow context**. If you see
`ERR_NOT_FOUND` (exit 3), your context is unset or stale — run `trickest workflow
use <name-or-id>` first. See [Configuration & Context](/docs/developer-tools/cli/configuration).
</Note>

## `trickest node`

| Subcommand | Description |
|---|---|
| `node ls\|list` | List nodes in the workflow |
| `node info\|get <name>` | Show node details |
| `node add <name>` | Add a node |
| `node set <name> <args...>` | Set node input(s) |
| `node label\|rename <name> <text>` | Set a node's label |
| `node rm\|remove <name>` | Remove a node |
| `node graph\|dag` | ASCII DAG visualization |
| `node distribute <name>` | Flag a node as distributed |
| `node undistribute <name>` | Remove distribution from a node |

### `node ls`

```bash
trickest node ls
```
```json
[{"name":"unfurl-2","type":"tool","info":"","upstream":["unfurl-3"],"downstream":["python-script-4"],"distribution":{"state":"none"}}, …]
```

Each node reports its `type`, `upstream`/`downstream` neighbors, and
`distribution` state.

| Flag | Description |
|---|---|
| `--type <type>` | Filter by `tool`, `script`, `module`, `primitive`, or `output` |
| `--filter <query>` | Filter by name |
| `--fields <fields>` | Comma-separated fields to show |
| `--format <json\|table\|plain>` | Per-command output format |
| `--include-infrastructure` | Include auto-generated distribution infrastructure (hidden by default) |

```bash
trickest node ls --type tool
trickest --output table node ls
trickest node ls --include-infrastructure    # reveal batch/distribution helpers
```

### `node info`

```bash
trickest node info subfinder
```

| Flag | Description |
|---|---|
| `--no-source` | Omit script source — lighter output when traversing many nodes |
| `--include-infrastructure` | Allow access to auto-generated infra nodes (rejected by default) |
| `--format <json\|table\|plain>` | Output format |

### `node add`

Add a node of any kind. The flags select what to add:

| Flag | Adds |
|---|---|
| `--tool <name>` | A tool node (fuzzy name match) |
| `--tool-id <id>` | A tool node by exact ID |
| `--script <lang>` | A script node (`python`, `bash`, `golang`, `node`) |
| `--module <name>` / `--module-id <id>` | A module node |
| `--primitive <type>` | A primitive (`STRING`, `BOOLEAN`, `URL`, `GIT`) |
| `--value <val>` | A primitive with auto-inferred type |

Connection & configuration flags:

| Flag | Description |
|---|---|
| `--from <node:port>` | Auto-connect from an existing node |
| `--to-port <port>` | Target input port for `--from` |
| `--flow <continue\|collect>` | Connection semantic when ports are auto-detected (`continue` = FILE→FILE, `collect` = FOLDER→FOLDER) |
| `--input <key=value>` | Set input values (repeatable) |
| `--label <text>` | Label the new node |
| `--code <code>` | Initial script source |

```bash
trickest node add subfinder --tool subfinder
trickest node add httpx --tool httpx --from subfinder
trickest node add tag --primitive STRING --value "example.com"
trickest node add parse --script python --code 'print("hi")' --from httpx
```

### `node set`

Set one or more inputs. Two equivalent syntaxes:

```bash
trickest node set subfinder domain example.com           # <name> <key> <value>
trickest node set subfinder domain=example.com threads=50  # key=value pairs
```

### `node label` / `node rm`

```bash
trickest node label subfinder "Subdomain discovery"
trickest node rm parse --force
```

### `node graph` (alias `node dag`)

ASCII visualization of the active workflow's DAG:

```bash
trickest node graph
```

## Distribution

Distribution fans a node out over its input so batches run in parallel. The CLI
auto-creates the supporting batch infrastructure (hidden from normal queries).

```bash
trickest node distribute resolve --input hosts --max 100
trickest node undistribute resolve
```

| `node distribute` flag | Description |
|---|---|
| `--input <name>` | Input port to distribute over (default: first FILE/FOLDER input) |
| `--min <n>` / `--max <n>` | Batch size bounds (batch mode) |
| `--per-line` | Per-line distribution instead of batch |

<Tip>
Use [`graph parallelism`](/docs/developer-tools/cli/graph) to discover which nodes
are worth distributing before you commit.
</Tip>

## Connecting nodes

`connect` and `disconnect` wire node outputs to node inputs. Node references use the
`node` or `node:port` format.

### `trickest connect`

```bash
trickest connect subfinder httpx                 # auto-detect ports
trickest connect subfinder:output httpx:input    # explicit ports
trickest connect add subfinder httpx             # 'add' is an explicit alias
```

| Flag | Description |
|---|---|
| `--flow <continue\|collect>` | Semantic when ports are auto-detected (explicit ports override) |
| `--format <json\|table\|plain>` | Output format |

### `trickest disconnect` (or `connect rm`)

```bash
trickest disconnect subfinder httpx
trickest disconnect subfinder httpx --all        # remove all edges between them
trickest connect rm subfinder httpx              # equivalent
```

| Flag | Description |
|---|---|
| `--all` | Disconnect all connections between the two nodes |

## Recipe: a linear pipeline

```bash
trickest workflow use "Discovery"
trickest node add domain --primitive STRING --value "example.com"
trickest node add subfinder --tool subfinder --from domain
trickest node add httpx --tool httpx --from subfinder
trickest node add nuclei --tool nuclei --from httpx
trickest graph validate
trickest save
```

## Related

<CardGroup cols={2}>
  <Card title="Graph Analysis" icon="sitemap" href="/docs/developer-tools/cli/graph">
    Validate the DAG and find critical paths and bottlenecks.
  </Card>
  <Card title="Workflows" icon="diagram-project" href="/docs/developer-tools/cli/workflows">
    Bulk-author the same structure with YAML `apply`/`patch`.
  </Card>
</CardGroup>

---
_Markdown source of https://trickest.com/docs/developer-tools/cli/nodes._