From 7954cb224bef74aa8d6b3510198ade108e874bf9 Mon Sep 17 00:00:00 2001
From: Musa <malikmusa1323@gmail.com>
Date: Thu, 12 Feb 2026 15:59:45 -0800
Subject: [PATCH] docs: add CLI reference documentation and update index

---
 docs/source/guides/observability/tracing.rst |  50 +---
 docs/source/index.rst                        |   1 +
 docs/source/resources/cli_reference.rst      | 286 +++++++++++++++++++
 3 files changed, 288 insertions(+), 49 deletions(-)
 create mode 100644 docs/source/resources/cli_reference.rst

diff --git a/docs/source/guides/observability/tracing.rst b/docs/source/guides/observability/tracing.rst
index 4b6d8090..e947e87f 100644
--- a/docs/source/guides/observability/tracing.rst
+++ b/docs/source/guides/observability/tracing.rst
@@ -497,55 +497,7 @@ tools like AWS X-Ray and Datadog, enhancing observability and facilitating faste
 Additional Resources
 --------------------
 
-CLI Reference
-~~~~~~~~~~~~~
-
-``planoai trace``
-  Trace requests captured by the local OTLP listener.
-
-  **Synopsis**
-
-  .. code-block:: console
-
-     $ planoai trace [TARGET] [OPTIONS]
-
-  **Targets**
-
-  - ``last`` (default): show the most recent trace.
-  - ``any``: allow interactive selection when available.
-  - ``<trace-id>``: full 32-hex trace ID.
-  - ``<short-id>``: first 8 hex characters.
-
-  **Options**
-
-  - ``--filter <pattern>``: limit displayed attributes to matching keys (supports ``*``).
-  - ``--where <key=value>``: match traces containing a specific attribute (repeatable, AND).
-  - ``--list``: list trace IDs only.
-  - ``--no-interactive``: disable interactive prompts/selections.
-  - ``--limit <n>``: limit the number of traces returned.
-  - ``--since <window>``: look back window (``5m``, ``2h``, ``1d``).
-  - ``--json``: output raw JSON instead of formatted output.
-  - ``--verbose, -v``: show all span attributes. By default, inbound/outbound
-    spans are displayed in a compact view.
-
-  **Environment**
-
-  - ``PLANO_TRACE_PORT``: gRPC port used by ``planoai trace`` to query traces
-    (defaults to ``4317``).
-
-``planoai trace listen``
-  Start a local OTLP/gRPC listener.
-
-  **Synopsis**
-
-  .. code-block:: console
-
-     $ planoai trace listen [OPTIONS]
-
-  **Options**
-
-  - ``--host <host>``: bind address (default: ``0.0.0.0``).
-  - ``--port <port>``: gRPC listener port (default: ``4317``).
+For full command documentation (including ``planoai trace`` and all other CLI commands), see :ref:`cli_reference`.
 
 External References
 ~~~~~~~~~~~~~~~~~~~
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 57952c92..7a2e5b60 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -62,4 +62,5 @@ Built by contributors to the widely adopted `Envoy Proxy <https://www.envoyproxy
       resources/tech_overview/tech_overview
       resources/deployment
       resources/configuration_reference
+      resources/cli_reference
       resources/llms_txt
diff --git a/docs/source/resources/cli_reference.rst b/docs/source/resources/cli_reference.rst
new file mode 100644
index 00000000..442bc263
--- /dev/null
+++ b/docs/source/resources/cli_reference.rst
@@ -0,0 +1,286 @@
+.. _cli_reference:
+
+CLI Reference
+=============
+
+This reference documents the full ``planoai`` command-line interface for day-to-day development, local testing, and operational workflows.
+Use this page as the canonical source for command syntax, options, and recommended usage patterns.
+
+Quick Navigation
+----------------
+
+- :ref:`cli_reference_global`
+- :ref:`cli_reference_up`
+- :ref:`cli_reference_down`
+- :ref:`cli_reference_build`
+- :ref:`cli_reference_logs`
+- :ref:`cli_reference_init`
+- :ref:`cli_reference_trace`
+- :ref:`cli_reference_prompt_targets`
+- :ref:`cli_reference_cli_agent`
+
+
+.. _cli_reference_global:
+
+Global CLI Usage
+----------------
+
+**Command**
+
+.. code-block:: console
+
+   $ planoai [COMMAND] [OPTIONS]
+
+**Common global options**
+
+- ``--help``: Show the top-level command menu.
+- ``--version``: Show installed CLI version and update status.
+
+**Help patterns**
+
+.. code-block:: console
+
+   $ planoai --help
+   $ planoai trace --help
+   $ planoai init --help
+
+
+.. _cli_reference_up:
+
+planoai up
+----------
+
+Start Plano using a configuration file.
+
+**Synopsis**
+
+.. code-block:: console
+
+   $ planoai up [FILE] [--path <dir>] [--foreground] [--with-tracing] [--tracing-port <port>]
+
+**Arguments**
+
+- ``FILE`` (optional): explicit path to config file.
+
+**Options**
+
+- ``--path <dir>``: directory to search for config (default ``.``).
+- ``--foreground``: run Plano in foreground.
+- ``--with-tracing``: start local OTLP/gRPC trace collector.
+- ``--tracing-port <port>``: collector port (default ``4317``).
+
+.. note::
+
+   If you use ``--with-tracing``, ensure that port 4317 is free and not already in use by Jaeger or any other observability services or processes. If port 4317 is occupied, the command will fail to start the trace collector.
+
+**Examples**
+
+.. code-block:: console
+
+   $ planoai up config.yaml
+   $ planoai up --path ./deploy
+   $ planoai up --with-tracing
+   $ planoai up --with-tracing --tracing-port 4318
+
+
+.. _cli_reference_down:
+
+planoai down
+------------
+
+Stop Plano (container/process stack managed by the CLI).
+
+**Synopsis**
+
+.. code-block:: console
+
+   $ planoai down
+
+
+.. _cli_reference_build:
+
+planoai build
+-------------
+
+Build Plano Docker image from repository source.
+
+**Synopsis**
+
+.. code-block:: console
+
+   $ planoai build
+
+
+.. _cli_reference_logs:
+
+planoai logs
+------------
+
+Stream Plano logs.
+
+**Synopsis**
+
+.. code-block:: console
+
+   $ planoai logs [--follow] [--debug]
+
+**Options**
+
+- ``--follow``: stream logs continuously.
+- ``--debug``: include additional gateway/debug streams.
+
+**Examples**
+
+.. code-block:: console
+
+   $ planoai logs
+   $ planoai logs --follow
+   $ planoai logs --follow --debug
+
+
+.. _cli_reference_init:
+
+planoai init
+------------
+
+Generate a new ``config.yaml`` using an interactive wizard, built-in templates, or a clean empty file.
+
+**Synopsis**
+
+.. code-block:: console
+
+   $ planoai init [--template <id> | --clean] [--output <path>] [--force] [--list-templates]
+
+**Options**
+
+- ``--template <id>``: create config from a built-in template id.
+- ``--clean``: create an empty config file.
+- ``--output, -o <path>``: output path (default ``config.yaml``).
+- ``--force``: overwrite existing output file.
+- ``--list-templates``: print available template IDs and exit.
+
+**Examples**
+
+.. code-block:: console
+
+   $ planoai init
+   $ planoai init --list-templates
+   $ planoai init --template coding_agent_routing
+   $ planoai init --clean --output ./config/config.yaml
+
+
+.. _cli_reference_trace:
+
+planoai trace
+-------------
+
+Inspect request traces from the local OTLP listener.
+
+**Synopsis**
+
+.. code-block:: console
+
+   $ planoai trace [TARGET] [OPTIONS]
+
+**Targets**
+
+- ``last`` (default): show most recent trace.
+- ``any``: consider all traces (interactive selection when terminal supports it).
+- ``listen``: start local OTLP listener.
+- ``down``: stop background listener.
+- ``<trace-id>``: full 32-hex trace id.
+- ``<short-id>``: first 8 hex chars of trace id.
+
+**Display options**
+
+- ``--filter <pattern>``: keep only matching attribute keys (supports ``*`` via "glob" syntax).
+- ``--where <key=value>``: locate traces containing key/value (repeatable, AND semantics).
+- ``--list``: list trace IDs instead of full trace output (use with ``--no-interactive`` to fetch plain-text trace IDs only).
+- ``--no-interactive``: disable interactive selection prompts.
+- ``--limit <n>``: limit returned traces.
+- ``--since <window>``: lookback window such as ``5m``, ``2h``, ``1d``.
+- ``--json``: emit JSON payloads.
+- ``--verbose``, ``-v``: show full attribute output (disable compact trimming). Useful for debugging internal attributes.
+
+**Listener options (for ``TARGET=listen``)**
+
+- ``--host <host>``: bind host (default ``0.0.0.0``).
+- ``--port <port>``: bind port (default ``4317``).
+- ``--debug``: run foreground listener and stream incoming span events to the console.
+
+.. note::
+
+   When using ``listen``, ensure that port 4317 is free and not already in use by Jaeger or any other observability services or processes. If port 4317 is occupied, the command will fail to start the trace collector. You cannot use other services on the same port when running.
+
+
+**Environment**
+
+- ``PLANO_TRACE_PORT``: query port used by ``planoai trace`` when reading traces (default ``4317``).
+
+**Examples**
+
+.. code-block:: console
+
+   # Start/stop listener
+   $ planoai trace listen
+   $ planoai trace down
+   $ planoai trace listen --debug
+
+   # Basic inspection
+   $ planoai trace
+   $ planoai trace 7f4e9a1c
+   $ planoai trace 7f4e9a1c0d9d4a0bb9bf5a8a7d13f62a
+
+   # Filtering and automation
+   $ planoai trace --where llm.model=openai/gpt-5.2 --since 30m
+   $ planoai trace --filter "http.*"
+   $ planoai trace --list --limit 5
+   $ planoai trace --where http.status_code=500 --json
+
+**Operational notes**
+
+- ``--debug`` is valid only when ``TARGET`` is ``listen``.
+- ``--host`` and ``--port`` are valid only when ``TARGET`` is ``listen``.
+- ``--list`` cannot be combined with a specific trace-id target.
+
+
+.. _cli_reference_prompt_targets:
+
+planoai prompt_targets
+----------------------
+
+Generate prompt-target metadata from Python methods.
+
+**Synopsis**
+
+.. code-block:: console
+
+   $ planoai prompt_targets --file <python-file>
+
+**Options**
+
+- ``--file, --f <python-file>``: required path to a ``.py`` source file.
+
+
+.. _cli_reference_cli_agent:
+
+planoai cli_agent
+-----------------
+
+Start an interactive CLI agent session against a running Plano deployment.
+
+**Synopsis**
+
+.. code-block:: console
+
+   $ planoai cli_agent claude [FILE] [--path <dir>] [--settings '<json>']
+
+**Arguments**
+
+- ``type``: currently ``claude``.
+- ``FILE`` (optional): config file path.
+
+**Options**
+
+- ``--path <dir>``: directory containing config file.
+- ``--settings <json>``: JSON settings payload for agent startup.