feat: add poly functions commands and grouped CLI help (DEVP-541, DEVP-543)

docs/docs/reference/cli.md

@@ -16,6 +16,15 @@ To see all available commands and options:
 poly --help
 ~~~
 
+Commands are listed under section headers so related ones stay together:
+
+| Section | Commands |
+|---|---|
+| Getting started | `init`, `start`, `login`, `studio`, `project` |
+| Project sync | `pull`, `push`, `status`, `revert`, `format`, `validate`, `diff`, `review`, `branch` |
+| Builder API | `deployments`, `conversations`, `audio-cache`, `functions`, `test`, `rtc`, `chat` |
+| Other | `docs`, `completion` |
+
 Each command also supports its own help output. For example:
 
 ~~~bash
@@ -262,7 +271,9 @@ poly revert file1.yaml file2.yaml
 
 ### `poly branch`
 
-Manage project branches.
+Manage project branches. `poly branch --help` splits its subcommands into
+**Branch lifecycle** (`list`, `create`, `switch`, `current`, `delete`, `merge`)
+and **Inspect** (`diff`, `review`, `status`).
 
 Examples:
 
@@ -679,6 +690,240 @@ poly audio-cache synthesize <entry_id> --text "Hi" --language en-US -o out.wav
 | `--path` | Base path to the project. Defaults to the current working directory. |
 | `--json` | Print a JSON summary on stdout instead of the success message (audio is still written to disk). |
 
+### `poly functions`
+
+Manage Functions using the public Functions REST API, scoped to the project's current branch.
+
+!!! note
+
+    This is a different mechanism from the local `functions/*.py` files synced by `poly pull` / `poly push` (see [Functions](functions.md)). `poly functions` talks to the Functions REST API directly and does not read or write local function files.
+
+`poly functions --help` splits its subcommands into four sections:
+
+| Section | Subcommands |
+|---|---|
+| Manage | `list`, `get`, `create`, `update`, `delete`, `duplicate` |
+| Run and inspect | `execute`, `references`, `type-definitions` |
+| Deploy | `validate`, `deploy`, `deployments` |
+| Lifecycle hooks | `start`, `end` |
+
+Examples:
+
+~~~bash
+poly functions list
+poly functions get <function_id>
+poly functions create --name my_func --description "desc" --code-file func.py
+poly functions execute <function_id> --args '{"x": 1}'
+poly functions deploy
+~~~
+
+#### `poly functions list`
+
+List the Functions defined on the current branch.
+
+~~~bash
+poly functions list
+poly functions list --limit 50 --offset 50
+~~~
+
+| Flag | Description |
+|---|---|
+| `--limit` | Max number of functions to return (1-50). Defaults to `20`. |
+| `--offset` | Number of functions to skip. Defaults to `0`. |
+| `--path` | Base path to the project. Defaults to the current working directory. |
+| `--json` | Print a single JSON object on stdout (machine-readable). |
+
+#### `poly functions get`
+
+Show a function's metadata, parameters and code.
+
+~~~bash
+poly functions get <function_id>
+~~~
+
+| Argument / Flag | Description |
+|---|---|
+| `function_id` | The function ID. Required. |
+| `--path` | Base path to the project. Defaults to the current working directory. |
+| `--json` | Print a single JSON object on stdout (machine-readable). |
+
+#### `poly functions create`
+
+Create a new Function on the current branch from a local code file.
+
+~~~bash
+poly functions create --name my_func --description "desc" --code-file func.py
+poly functions create --name my_func --description "desc" --code-file func.py \
+    --parameters '[{"name": "x", "type": "str", "description": "an x"}]'
+~~~
+
+| Flag | Description |
+|---|---|
+| `--name` | The function name. Required. |
+| `--description` | The function description. Required. |
+| `--code-file` | Local path to the function's Python source. Required. |
+| `--parameters` | JSON list of parameter specs. |
+| `--path` | Base path to the project. Defaults to the current working directory. |
+| `--json` | Print a single JSON object on stdout (machine-readable). |
+
+A name collision returns a conflict and is not overridable — pick a different name.
+
+#### `poly functions update`
+
+Update a Function's name, description, code or parameters. At least one field must be supplied.
+
+~~~bash
+poly functions update <function_id> --code-file func.py
+poly functions update <function_id> --description "new desc"
+poly functions update <function_id> --name renamed --force
+~~~
+
+| Argument / Flag | Description |
+|---|---|
+| `function_id` | The function ID. Required. |
+| `--name` | New function name. |
+| `--description` | New function description. |
+| `--code-file` | Local path to the replacement Python source. |
+| `--parameters` | JSON list of parameter specs. |
+| `-f`, `--force` | Override an orphaned-reference conflict, leaving flow steps pointing at nothing. |
+| `--path` | Base path to the project. Defaults to the current working directory. |
+| `--json` | Print a single JSON object on stdout (machine-readable). |
+
+If flow steps reference the function in a way the change would break, the command reports the conflicting steps and exits non-zero. Re-run with `--force` to apply it anyway. With `--json`, the conflicting steps are returned under `orphaned_references`.
+
+#### `poly functions delete`
+
+Delete a Function from the current branch.
+
+~~~bash
+poly functions delete <function_id>
+poly functions delete <function_id> --force
+~~~
+
+| Argument / Flag | Description |
+|---|---|
+| `function_id` | The function ID. Required. |
+| `-f`, `--force` | Override an orphaned-reference conflict, leaving flow steps pointing at nothing. |
+| `--path` | Base path to the project. Defaults to the current working directory. |
+| `--json` | Print a single JSON object on stdout (machine-readable). |
+
+#### `poly functions execute`
+
+Execute a Function and print its return value, logs and runtime.
+
+~~~bash
+poly functions execute <function_id>
+poly functions execute <function_id> --args '{"x": 1}'
+~~~
+
+| Argument / Flag | Description |
+|---|---|
+| `function_id` | The function ID. Required. |
+| `--args` | JSON object of arguments to pass to the function. Defaults to `{}`. |
+| `--path` | Base path to the project. Defaults to the current working directory. |
+| `--json` | Print a single JSON object on stdout (machine-readable). |
+
+#### `poly functions duplicate`
+
+Copy a Function on the current branch.
+
+~~~bash
+poly functions duplicate <function_id>
+poly functions duplicate <function_id> --name my_func_copy
+~~~
+
+| Argument / Flag | Description |
+|---|---|
+| `function_id` | The function ID to copy. Required. |
+| `--name` | Name for the copy. Defaults to a server-generated name. |
+| `--path` | Base path to the project. Defaults to the current working directory. |
+| `--json` | Print a single JSON object on stdout (machine-readable). |
+
+#### `poly functions deploy`
+
+Deploy every draft Function on the current branch.
+
+~~~bash
+poly functions deploy
+~~~
+
+| Flag | Description |
+|---|---|
+| `--path` | Base path to the project. Defaults to the current working directory. |
+| `--json` | Print a single JSON object on stdout (machine-readable). |
+
+#### `poly functions validate`
+
+Check every Function on the current branch for syntax errors and orphaned flow-step references.
+
+~~~bash
+poly functions validate
+~~~
+
+| Flag | Description |
+|---|---|
+| `--path` | Base path to the project. Defaults to the current working directory. |
+| `--json` | Print a single JSON object on stdout (machine-readable). |
+
+#### `poly functions references`
+
+List the flow steps that call a Function. Useful before a rename or delete.
+
+~~~bash
+poly functions references <function_id>
+~~~
+
+| Argument / Flag | Description |
+|---|---|
+| `function_id` | The function ID. Required. |
+| `--path` | Base path to the project. Defaults to the current working directory. |
+| `--json` | Print a single JSON object on stdout (machine-readable). |
+
+#### `poly functions type-definitions`
+
+Print the `Conversation`/`Flow` type stubs available to a Function, for IDE autocomplete.
+
+~~~bash
+poly functions type-definitions <function_id>
+poly functions type-definitions <function_id> > stubs.py
+~~~
+
+| Argument / Flag | Description |
+|---|---|
+| `function_id` | The function ID. Required. |
+| `--path` | Base path to the project. Defaults to the current working directory. |
+| `--json` | Print a single JSON object on stdout (machine-readable). |
+
+#### `poly functions deployments`
+
+Show the deployment history for the project's Functions across environments.
+
+~~~bash
+poly functions deployments
+~~~
+
+| Flag | Description |
+|---|---|
+| `--path` | Base path to the project. Defaults to the current working directory. |
+| `--json` | Print a single JSON object on stdout (machine-readable). |
+
+#### `poly functions start` / `poly functions end`
+
+Read or replace the branch's `start_function` and `end_function`. Each takes a `get` or `update` subcommand.
+
+~~~bash
+poly functions start get
+poly functions start update --code-file start.py
+poly functions end get
+poly functions end update --code-file end.py
+~~~
+
+| Argument / Flag | Description |
+|---|---|
+| `--code-file` | Local path to the replacement source. Required for `update`. |
+| `--path` | Base path to the project. Defaults to the current working directory. |
+| `--json` | Print a single JSON object on stdout (machine-readable). |
+
 ### `poly docs`
 
 Output resource documentation.
@@ -844,6 +1089,12 @@ poly audio-cache update-file <entry_id> --file replacement.wav --json
 poly audio-cache delete <entry_id> --json
 poly audio-cache bulk-delete --ids id1,id2 --json
 poly audio-cache synthesize <entry_id> --text "Hello" --json
+poly functions list --json
+poly functions get <function_id> --json
+poly functions create --name my_func --description "desc" --code-file func.py --json
+poly functions execute <function_id> --args '{"x": 1}' --json
+poly functions validate --json
+poly functions deploy --json
 ~~~
 
 When `--json` is used:

docs/docs/reference/functions.md

@@ -12,6 +12,8 @@ They can be called by the model, used as flow steps, or run automatically at cal
 
 Functions are how the ADK handles behavior that should not be left to prompt interpretation alone.
 
+To manage functions programmatically over the REST API instead of via local files, see [`poly functions`](cli.md#poly-functions).
+
 ## Where functions live
 
 ~~~text

src/poly/cli.py

@@ -14,11 +14,19 @@
 
 from poly.cli_commands.audio_cache import AudioCacheCommand
 from poly.cli_commands.auth import LoginCommand, StartCommand
-from poly.cli_commands.base import BaseCommand, Parents
+from poly.cli_commands.base import (
+    COMMAND_GROUP_ORDER,
+    BaseCommand,
+    GroupedHelpFormatter,
+    Parents,
+    add_grouped_subparsers,
+    group_subcommands,
+)
 from poly.cli_commands.branch import BranchCommand
 from poly.cli_commands.chat import ChatCommand
 from poly.cli_commands.conversations import ConversationsCommand
 from poly.cli_commands.deployments import DeploymentsCommand
+from poly.cli_commands.functions import FunctionsCommand
 from poly.cli_commands.project import InitCommand, ProjectCommand, StudioCommand
 from poly.cli_commands.review import ReviewCommand
 from poly.cli_commands.rtc import RTCCommand
@@ -55,6 +63,7 @@
     DeploymentsCommand,
     ConversationsCommand,
     AudioCacheCommand,
+    FunctionsCommand,
     TestingCommand,
     RTCCommand,
     ChatCommand,
@@ -77,7 +86,7 @@ def _create_parser(self):
             _version = get_package_version("polyai-adk")
         except Exception:
             _version = "unknown"
-        parser = ArgumentParser()
+        parser = ArgumentParser(formatter_class=GroupedHelpFormatter)
         parser.add_argument(
             "-v",
             "--version",
@@ -121,11 +130,18 @@ def _create_parser(self):
             verbose=verbose_parent, json=json_parent, debug=debug_parent, path=path_parent
         )
 
-        subparsers = parser.add_subparsers(dest="command", required=True)
+        subparsers = add_grouped_subparsers(parser, dest="command", metavar="<command>")
 
         for command in self.commands:
             command.add_arguments(subparsers, parents=parents)
 
+        # Split the (long) flat command list into titled sections for --help.
+        group_subcommands(
+            subparsers,
+            {command.command: command.group for command in self.commands},
+            COMMAND_GROUP_ORDER,
+        )
+
         return parser
 
     def _run_command(self, args):

src/poly/cli_commands/audio_cache.py

@@ -10,7 +10,7 @@
 from argparse import ArgumentParser, Namespace, RawTextHelpFormatter, _SubParsersAction
 from typing import Optional
 
-from poly.cli_commands.base import BaseCommand, Parents
+from poly.cli_commands.base import BUILDER_API_GROUP, BaseCommand, Parents
 from poly.cli_commands.shared import load_project
 from poly.handlers.interface import AgentStudioInterface
 from poly.output.json_output import json_print
@@ -21,6 +21,8 @@ class AudioCacheCommand(BaseCommand):
 
     command = "audio-cache"
 
+    group = BUILDER_API_GROUP
+
     @classmethod
     def add_arguments(cls, subparsers: _SubParsersAction[ArgumentParser], parents: Parents) -> None:
         """Register the ``audio-cache`` subcommand tree."""

src/poly/cli_commands/auth.py

@@ -7,7 +7,7 @@
 import sys
 from argparse import ArgumentParser, Namespace, _SubParsersAction
 
-from poly.cli_commands.base import BaseCommand, Parents
+from poly.cli_commands.base import GETTING_STARTED_GROUP, BaseCommand, Parents
 from poly.cli_commands.project import ProjectCommand
 from poly.handlers.auth0_handler import Auth0Handler
 from poly.handlers.interface import REGIONS, AgentStudioInterface
@@ -116,6 +116,8 @@ class StartCommand(BaseCommand):
 
     command = "start"
 
+    group = GETTING_STARTED_GROUP
+
     @classmethod
     def add_arguments(cls, subparsers: _SubParsersAction[ArgumentParser], parents: Parents) -> None:
         """Register the ``start`` subcommand."""
@@ -226,6 +228,8 @@ class LoginCommand(BaseCommand):
 
     command = "login"
 
+    group = GETTING_STARTED_GROUP
+
     @classmethod
     def add_arguments(cls, subparsers: _SubParsersAction[ArgumentParser], parents: Parents) -> None:
         """Register the ``login`` subcommand."""