dfx-ctl - Control and Inspection Tool

Overview

dfx-ctl is the command-line control tool of the dfx project.

It is used to interact with running dfx components, both at the instance level and at the daemon level, and acts as the primary human and script-facing control plane for dfx.

Conceptually, dfx-ctl plays a role similar to tools such as docker or kubectl: it is an imperative, stateless CLI that connects to a target, performs an operation, prints the result, and exits.

Role and positioning

dfx-ctl serves two complementary roles:

• Operator tool:
  • control and monitor running dfx instances,
  • manage instance lifecycle through the dfxd daemon,
  • inspect runtime state and diagnose issues.
• Developer tool:
  • explore and modify graphs interactively,
  • test runtime behavior,
  • access lower-level commands when the CLI does not yet expose a dedicated high-level command.

These roles are intentionally combined in a single tool.

Control plane model

dfx-ctl communicates over Unix domain sockets with:

• dfx instances, exposing runtime and graph control interfaces,
• dfxd, the daemon responsible for instance management.

Depending on the invoked subcommand, dfx-ctl may target either a specific instance or the daemon itself.

Graph mutability

dfx is designed around the idea of runtime graph mutability.

Through dfx-ctl, it is possible to:

• add or remove nodes,
• add or remove channels,
• modify configuration,
• inspect or export the current graph state,

at any point during execution, while the instance is running.

These operations are expected to be safe and supported by the runtime. dfx-ctl does not treat the graph as immutable once started.

Stateless design

dfx-ctl is a strictly stateless program:

• it does not persist configuration,
• it does not cache state,
• it does not maintain long-lived sessions.

Each invocation:

• connects to the target,
• sends one or more commands,
• waits for the response,
• and exits.

Any persistence (for example, storing exported graphs) is the responsibility of the caller.

Command philosophy

Commands exposed by dfx-ctl are intentionally high-level and semantic.

They are grouped by domain (node, channel, graph, config, …) and reflect what the user wants to do, not the details of the underlying protocol.

The CLI does not aim to be a thin one-to-one mapping of protocol messages.

Raw command access

The raw command provides a low-level escape hatch.

It allows sending arbitrary commands and parameters directly to a dfx or dfxd control socket, bypassing the structured CLI interface.

This command exists primarily to:

• facilitate development and debugging,
• interact with newer runtimes before dfx-ctl has been updated,
• avoid manual socket or protocol handling.

raw should be considered a backdoor rather than a stable, user-friendly interface.

Stability and compatibility

Command sets and JSON schemas are versioned and documented.

However, as dfx is a personal project, dfx-ctl follows a best-effort compatibility model:

• backward compatibility is not guaranteed,
• new commands and fields may be added over time,
• breaking changes may occur when the architecture evolves.

Users relying on dfx-ctl for automation should be prepared to adapt scripts accordingly.

Typical usage scenarios

Common use cases include:

• starting, stopping, and inspecting dfx instances via dfxd,
• interactively modifying a running graph,
• inspecting nodes, channels, and configuration at runtime,
• exporting or validating graph definitions,
• debugging or experimenting with runtime behavior.

Examples

The following examples illustrate typical interactions with dfx-ctl. They are intentionally concise and focus on intent rather than exhaustive option coverage.

Inspect a running instance

List all nodes currently present in a running graph:

dfx-ctl node list

Retrieve detailed information about a specific node:

dfx-ctl node get my-node

Modify a running graph

Add a new node while the instance is running:

dfx-ctl node add logger --type Log

Connect two existing nodes:

dfx-ctl channel add gen.out logger.in

Remove a node from the graph:

dfx-ctl node remove logger

Export and validate graphs

Export the current runtime graph to a file:

dfx-ctl graph export --output graph.dfx

Validate a graph definition before importing it:

dfx-ctl graph validate graph.dfx

Non-goals

dfx-ctl is not:

• a runtime executor (that role belongs to dfx),
• a long-running supervisor (that role belongs to dfxd),
• a graphical editor or visual design tool.