From 4ddf36ae538eb2c0a31253397fbb5256d4dfe91c Mon Sep 17 00:00:00 2001
From: Catarina Paralta <clouropa@cisco.com>
Date: Fri, 27 Mar 2026 15:30:07 +0000
Subject: [PATCH] docs(dir): add local daemon operations to CLI reference

Signed-off-by: Catarina Paralta <clouropa@cisco.com>
---
 docs/dir/directory-cli-reference.md | 84 +++++++++++++++++++++++++++++
 docs/dir/directory-cli.md           | 26 +++++++++
 2 files changed, 110 insertions(+)

diff --git a/docs/dir/directory-cli-reference.md b/docs/dir/directory-cli-reference.md
index 788f85b..d1912ad 100644
--- a/docs/dir/directory-cli-reference.md
+++ b/docs/dir/directory-cli-reference.md
@@ -1,5 +1,89 @@
 # Directory CLI Command Reference
 
+## Daemon Operations
+
+The daemon commands run a self-contained local directory server that bundles the gRPC apiserver and reconciler into a single process with embedded SQLite and a filesystem OCI store. All state is stored under `~/.agntcy/dir/` by default.
+
+### `dirctl daemon start`
+
+Starts the local directory daemon in the foreground. The process blocks until `SIGINT` or `SIGTERM` is received.
+
+The daemon starts a gRPC apiserver on `localhost:8888` and runs all reconciler tasks (regsync, indexer, name resolution, signature verification) in-process. It uses SQLite for persistence and a local filesystem OCI store, so no external dependencies (PostgreSQL, container registry, etc.) are required.
+
+A PID file is written to the data directory to prevent multiple instances from running simultaneously.
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--data-dir` | Data directory for daemon state | `~/.agntcy/dir/` |
+
+??? example
+
+    ```bash
+    # Start the daemon (foreground, blocks until signal)
+    dirctl daemon start
+
+    # Start with a custom data directory
+    dirctl daemon start --data-dir /path/to/data
+
+    # Run in the background using shell job control
+    dirctl daemon start &
+    ```
+
+**Data directory layout:**
+
+```
+~/.agntcy/dir/
+├── dir.db          # SQLite database
+├── store/          # Filesystem OCI store
+├── routing/        # DHT routing datastore
+└── daemon.pid      # PID file for lifecycle management
+```
+
+### `dirctl daemon stop`
+
+Stops a running daemon by sending `SIGTERM` to the process recorded in the PID file. The command waits for the process to exit gracefully and cleans up the PID file.
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--data-dir` | Data directory for daemon state | `~/.agntcy/dir/` |
+
+??? example
+
+    ```bash
+    # Stop the running daemon
+    dirctl daemon stop
+
+    # Stop a daemon using a custom data directory
+    dirctl daemon stop --data-dir /path/to/data
+    ```
+
+### `dirctl daemon status`
+
+Checks whether the daemon is currently running by inspecting the PID file.
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--data-dir` | Data directory for daemon state | `~/.agntcy/dir/` |
+
+??? example
+
+    ```bash
+    # Check daemon status
+    dirctl daemon status
+    ```
+
+    Example output when running:
+
+    ```
+    Daemon is running (PID 12345)
+    ```
+
+    Example output when stopped:
+
+    ```
+    Daemon is not running
+    ```
+
 ## Storage Operations
 
 ### `dirctl push <file>`
diff --git a/docs/dir/directory-cli.md b/docs/dir/directory-cli.md
index 5dc6cfd..abd8f6a 100644
--- a/docs/dir/directory-cli.md
+++ b/docs/dir/directory-cli.md
@@ -43,6 +43,31 @@ The Directory CLI can be installed in the following ways:
 
 ## Quick Start
 
+### Local Daemon (No External Dependencies)
+
+The fastest way to get a fully functional local directory is to run the built-in daemon:
+
+```bash
+# Start the daemon (runs apiserver + reconciler in one process)
+dirctl daemon start
+```
+
+This starts a gRPC server on `localhost:8888` with embedded SQLite and a filesystem OCI store. All data is stored under `~/.agntcy/dir/` by default. No PostgreSQL, Docker, or external registry required.
+
+Once the daemon is running, use any `dirctl` command against it:
+
+```bash
+dirctl --server-addr localhost:8888 push my-agent.json
+```
+
+To stop the daemon:
+
+```bash
+dirctl daemon stop
+```
+
+### Using an Existing Server
+
 The following example demonstrates how to store, publish, search, and retrieve a record using the Directory CLI:
 
 1. Store a record
@@ -442,6 +467,7 @@ dirctl --spiffe-socket-path /run/spire/sockets/agent.sock routing list
 
 The CLI follows a clear service-based organization:
 
+- **Daemon**: Local directory server (`daemon start`, `daemon stop`, `daemon status`).
 - **Auth**: GitHub OAuth authentication (`auth login`, `auth logout`, `auth status`).
 - **Storage**: Direct record management (`push`, `pull`, `delete`, `info`).
 - **Import**: Batch imports from external registries (`import`).