feat(poppy): add the auth0 poppy commands

README.md

@@ -249,6 +249,16 @@ auth0 login --domain <domain> --client-id <client-id> --client-secret <client-se
 auth0 login --domain <domain> --client-id <client-id> --client-assertion-private-key <path-to-private-key / private-key> --client-assertion-signing-alg <signing-algorithm>
 ```
 
+### Extra scopes for `auth0 poppy agents`
+
+`auth0 poppy setup`, `config` and `doctor` work with the default login scopes. The `auth0 poppy agents` commands also need the `read:agents`, `create:agents` and `delete:agents` scopes, which are not requested by default because Agent as Principal is still in limited early access. If your tenant has it, log in again with them:
+
+```bash
+auth0 login --scopes read:agents,create:agents,delete:agents
+```
+
+If a scope is missing, the command stops before changing anything and prints the exact `auth0 login --scopes ...` command to run.
+
 ### Re-authentication
 
 When your access token expires, the CLI will prompt you to confirm whether to continue with your default tenant or select a different one:
@@ -282,6 +292,7 @@ Select **y** to proceed with your default tenant, or **N** to choose a different
 - [auth0 logout](https://auth0.github.io/auth0-cli/auth0_logout.html) - Log out of a tenant's session
 - [auth0 logs](https://auth0.github.io/auth0-cli/auth0_logs.html) - View tenant logs
 - [auth0 orgs](https://auth0.github.io/auth0-cli/auth0_orgs.html) - Manage resources for organizations
+- [auth0 poppy](https://auth0.github.io/auth0-cli/auth0_poppy.html) - (Experimental) Prepare your company for personal agents with the Personal Agent Protocol (Poppy)
 - [auth0 protection](https://auth0.github.io/auth0-cli/auth0_protection.html) - Manage resources for attack protection
 - [auth0 quickstarts](https://auth0.github.io/auth0-cli/auth0_quickstarts.html) - Quickstart support for getting bootstrapped
 - [auth0 refresh-tokens](https://auth0.github.io/auth0-cli/auth0_refresh-tokens.html) - Manage resources for refresh tokens

docs/auth0_poppy.md

@@ -0,0 +1,18 @@
+---
+layout: default
+has_toc: false
+has_children: true
+---
+# auth0 poppy
+
+(Experimental) Prepares your company for personal agents, using the Personal Agent Protocol (Poppy). Poppy settings are spread across the tenant, an API and a web app, and the discovery files on your website must repeat Auth0's values exactly. These commands set that up, write one config file, a `poppy.json` document, for your web and API SDKs, manage the agents you allow, and check the whole chain before an agent arrives.
+
+**Warning:** This command is experimental and is subject to change in future versions.
+
+## Commands
+
+- [auth0 poppy agents](auth0_poppy_agents.md) - Manage the agents your company allows
+- [auth0 poppy config](auth0_poppy_config.md) - Rebuild the Poppy config file from the tenant
+- [auth0 poppy doctor](auth0_poppy_doctor.md) - Check the Poppy discovery chain end to end
+- [auth0 poppy setup](auth0_poppy_setup.md) - Turn on Poppy for the tenant, an API and a web app
+

docs/auth0_poppy_agents.md

@@ -0,0 +1,18 @@
+---
+layout: default
+has_toc: false
+has_children: true
+---
+# auth0 poppy agents
+
+(Experimental) Manages the personal agents your company allows. In the beta, Auth0 accepts only agents your company registers, so the registered list is the allow list. A Poppy agent is an agent app with a grant to a Poppy API.
+
+**Warning:** This command is experimental and is subject to change in future versions.
+
+## Commands
+
+- [auth0 poppy agents list](auth0_poppy_agents_list.md) - List the registered agents
+- [auth0 poppy agents register](auth0_poppy_agents_register.md) - Register an agent so it can sign in to your company
+- [auth0 poppy agents remove](auth0_poppy_agents_remove.md) - Remove an agent's Poppy access
+- [auth0 poppy agents show](auth0_poppy_agents_show.md) - Show the details of an agent
+

docs/auth0_poppy_agents_list.md

@@ -0,0 +1,53 @@
+---
+layout: default
+parent: auth0 poppy agents
+has_toc: false
+---
+# auth0 poppy agents list
+
+(Experimental) Lists the Poppy agents registered with your company, with their metadata status and the APIs each one can use. By default it shows only agents that have a grant to a Poppy API; use `--all` to include the others.
+
+**Warning:** This command is experimental and is subject to change in future versions.
+
+## Usage
+```
+auth0 poppy agents list [flags]
+```
+
+## Examples
+
+```
+  auth0 poppy agents list
+  auth0 poppy agents list --all
+  auth0 poppy agents list --json
+```
+
+
+## Flags
+
+```
+      --all            Include agents that have no grant to a Poppy API.
+      --json           Output in json format.
+      --json-compact   Output in compact json format.
+```
+
+
+## Inherited Flags
+
+```
+      --agent-mode      Output JSON, disable prompts and colors. Auto-enabled for AI agents; set AUTH0_AGENT_MODE=false to disable.
+      --debug           Enable debug mode.
+      --no-color        Disable colors.
+      --no-input        Disable interactivity.
+      --tenant string   Specific tenant to use.
+```
+
+
+## Related Commands
+
+- [auth0 poppy agents list](auth0_poppy_agents_list.md) - List the registered agents
+- [auth0 poppy agents register](auth0_poppy_agents_register.md) - Register an agent so it can sign in to your company
+- [auth0 poppy agents remove](auth0_poppy_agents_remove.md) - Remove an agent's Poppy access
+- [auth0 poppy agents show](auth0_poppy_agents_show.md) - Show the details of an agent
+
+

docs/auth0_poppy_agents_register.md

@@ -0,0 +1,59 @@
+---
+layout: default
+parent: auth0 poppy agents
+has_toc: false
+---
+# auth0 poppy agents register
+
+(Experimental) Registers an agent from the URL of its metadata document. The command previews the document, creates or updates the agent app, creates the agent record and grants the agent your Poppy APIs. It changes the tenant only: the config file is not written, and is read only to show the hints of the scopes on offer. By default it grants every Poppy API of the tenant. In a terminal it asks which scopes to grant; otherwise pass `--scopes` or `--all-scopes`. DPoP is required only with `--require-dpop`. Running it again refreshes the agent app from the current document and changes nothing else, which is also how you pick up keys the agent has rotated.
+
+**Warning:** This command is experimental and is subject to change in future versions.
+
+## Usage
+```
+auth0 poppy agents register [agent-url] [flags]
+```
+
+## Examples
+
+```
+  auth0 poppy agents register https://muse.example/agent.json
+  auth0 poppy agents register https://muse.example/agent.json --api https://api.shop.example --scopes orders:read --yes
+  auth0 poppy agents register https://muse.example/agent.json --all-scopes --require-dpop
+```
+
+
+## Flags
+
+```
+      --all-scopes        Grant every offered scope. Mutually exclusive with --scopes.
+      --api stringArray   A Poppy API, by id or identifier. Repeat for several. When registering an agent, the Poppy APIs to grant (default: every Poppy API of the tenant).
+      --json              Output in json format.
+      --json-compact      Output in compact json format.
+      --name string       The Company's name for the config file. When registering an agent, the agent's name.
+      --out string        Path of the config file. (default "auth0-poppy.json")
+      --require-dpop      Require DPoP-bound tokens for the agent. Off by default.
+      --scopes strings    Comma-separated list of scopes to grant. Without a terminal, pass this or --all-scopes. Mutually exclusive with --all-scopes.
+      --yes               Skip confirmation.
+```
+
+
+## Inherited Flags
+
+```
+      --agent-mode      Output JSON, disable prompts and colors. Auto-enabled for AI agents; set AUTH0_AGENT_MODE=false to disable.
+      --debug           Enable debug mode.
+      --no-color        Disable colors.
+      --no-input        Disable interactivity.
+      --tenant string   Specific tenant to use.
+```
+
+
+## Related Commands
+
+- [auth0 poppy agents list](auth0_poppy_agents_list.md) - List the registered agents
+- [auth0 poppy agents register](auth0_poppy_agents_register.md) - Register an agent so it can sign in to your company
+- [auth0 poppy agents remove](auth0_poppy_agents_remove.md) - Remove an agent's Poppy access
+- [auth0 poppy agents show](auth0_poppy_agents_show.md) - Show the details of an agent
+
+

docs/auth0_poppy_agents_remove.md

@@ -0,0 +1,55 @@
+---
+layout: default
+parent: auth0 poppy agents
+has_toc: false
+---
+# auth0 poppy agents remove
+
+(Experimental) Removes the agent's Poppy access: its grants to your Poppy APIs. It changes the tenant only, and does not touch the config file. When the agent has no other grants it also removes the agent record and the app, so registering the agent again creates a new app and its users must sign in again. When the app has other grants, only the Poppy access is removed and the other grants are listed, unless you pass `--remove-all-grants`; in a terminal you are asked which to do. Deleting the app revokes its refresh tokens; when the app is kept, its refresh tokens are not revoked. Access tokens already issued stay valid until they expire. Use `--dry-run` to print what would be removed, and `--force` to skip the confirmation.
+
+**Warning:** This command is experimental and is subject to change in future versions.
+
+## Usage
+```
+auth0 poppy agents remove [agent-url|agent-id] [flags]
+```
+
+## Examples
+
+```
+  auth0 poppy agents remove https://muse.example/agent.json
+  auth0 poppy agents remove https://muse.example/agent.json --dry-run
+  auth0 poppy agents remove <agent-id> --remove-all-grants --force
+```
+
+
+## Flags
+
+```
+      --dry-run             Print the plan and change nothing.
+      --force               Skip confirmation.
+      --json                Output in json format.
+      --json-compact        Output in compact json format.
+      --remove-all-grants   Also delete the app's other grants, then the agent record and the app.
+```
+
+
+## Inherited Flags
+
+```
+      --agent-mode      Output JSON, disable prompts and colors. Auto-enabled for AI agents; set AUTH0_AGENT_MODE=false to disable.
+      --debug           Enable debug mode.
+      --no-color        Disable colors.
+      --no-input        Disable interactivity.
+      --tenant string   Specific tenant to use.
+```
+
+
+## Related Commands
+
+- [auth0 poppy agents list](auth0_poppy_agents_list.md) - List the registered agents
+- [auth0 poppy agents register](auth0_poppy_agents_register.md) - Register an agent so it can sign in to your company
+- [auth0 poppy agents remove](auth0_poppy_agents_remove.md) - Remove an agent's Poppy access
+- [auth0 poppy agents show](auth0_poppy_agents_show.md) - Show the details of an agent
+
+

docs/auth0_poppy_agents_show.md

@@ -0,0 +1,52 @@
+---
+layout: default
+parent: auth0 poppy agents
+has_toc: false
+---
+# auth0 poppy agents show
+
+(Experimental) Shows one agent's details, given its URL or agent ID. It also checks the agent's metadata document live and tells you whether the keys Auth0 stored are still current, so you know when the agent needs to be registered again.
+
+**Warning:** This command is experimental and is subject to change in future versions.
+
+## Usage
+```
+auth0 poppy agents show [agent-url|agent-id] [flags]
+```
+
+## Examples
+
+```
+  auth0 poppy agents show https://muse.example/agent.json
+  auth0 poppy agents show <agent-id>
+  auth0 poppy agents show https://muse.example/agent.json --json
+```
+
+
+## Flags
+
+```
+      --json           Output in json format.
+      --json-compact   Output in compact json format.
+```
+
+
+## Inherited Flags
+
+```
+      --agent-mode      Output JSON, disable prompts and colors. Auto-enabled for AI agents; set AUTH0_AGENT_MODE=false to disable.
+      --debug           Enable debug mode.
+      --no-color        Disable colors.
+      --no-input        Disable interactivity.
+      --tenant string   Specific tenant to use.
+```
+
+
+## Related Commands
+
+- [auth0 poppy agents list](auth0_poppy_agents_list.md) - List the registered agents
+- [auth0 poppy agents register](auth0_poppy_agents_register.md) - Register an agent so it can sign in to your company
+- [auth0 poppy agents remove](auth0_poppy_agents_remove.md) - Remove an agent's Poppy access
+- [auth0 poppy agents show](auth0_poppy_agents_show.md) - Show the details of an agent
+
+

docs/auth0_poppy_config.md

@@ -0,0 +1,61 @@
+---
+layout: default
+parent: auth0 poppy
+has_toc: false
+---
+# auth0 poppy config
+
+(Experimental) Rebuilds the config file from the tenant without changing the tenant, so CI and deploys can refresh it safely. It reads the tenant, adds the values Auth0 does not store, and writes the file. If the tenant is not set up for Poppy, it exits with an error naming the missing setting. The config file is for one website, so with several company domains pass `--company-domain` to pick the one this app serves. The file is a protocol 0.4 `poppy.json` document and nothing else, so your web SDK can serve it as `/.well-known/poppy.json`. A file written for 0.3 is upgraded, and members of the file that the CLI does not use are kept. In a terminal it asks whether signing in to the browser gives an agent full access to the user's account on your website (`web.unscoped`), unless you pass `--web-unscoped` or the file already has a value. The file holds no API identifier and no web app, so without `--api` the APIs are the Poppy APIs of the tenant that the `apis` entries of the existing file are at, and without `--app` the web app is the only app of the tenant that has the browser join on. When that does not settle on one, the command stops and asks for `--api` or `--app`.
+
+**Warning:** This command is experimental and is subject to change in future versions.
+
+## Usage
+```
+auth0 poppy config [flags]
+```
+
+## Examples
+
+```
+  auth0 poppy config
+  auth0 poppy config --company-domain shop.example --out ./config/auth0-poppy.json
+  auth0 poppy config --company-domain shop.example --api https://api.shop.example --app "Shop Web" --json
+```
+
+
+## Flags
+
+```
+      --api stringArray         A Poppy API, by id or identifier. Repeat for several. When registering an agent, the Poppy APIs to grant (default: every Poppy API of the tenant).
+      --api-url stringArray     Where an API's OpenAPI document lives, as <identifier>=<openapi url>. Repeat for several. Asked if the config file has no entry for the API, with <origin>/openapi.json as the default when the identifier is a URL.
+      --app string              Client ID or name of the web app used for the browser join.
+      --company-domain string   The Company's website host, such as shop.example. With several company domains, picks the one this app serves.
+      --force-config            Overwrite a config file that belongs to a different issuer.
+      --hint stringArray        Hints for a scope, as name=changes:irreversible,personal_data:true. Repeat for several.
+      --json                    Output in json format.
+      --json-compact            Output in compact json format.
+      --name string             The Company's name for the config file. When registering an agent, the agent's name.
+      --out string              Path of the config file. (default "auth0-poppy.json")
+      --web-unscoped            Set web.unscoped in the config file: true when your website treats poppy:browser-sign-in as the account's full access on the website. auth0 poppy doctor then reminds you to check the description of poppy:browser-sign-in. Asked in a terminal when the config file has no value.
+```
+
+
+## Inherited Flags
+
+```
+      --agent-mode      Output JSON, disable prompts and colors. Auto-enabled for AI agents; set AUTH0_AGENT_MODE=false to disable.
+      --debug           Enable debug mode.
+      --no-color        Disable colors.
+      --no-input        Disable interactivity.
+      --tenant string   Specific tenant to use.
+```
+
+
+## Related Commands
+
+- [auth0 poppy agents](auth0_poppy_agents.md) - Manage the agents your company allows
+- [auth0 poppy config](auth0_poppy_config.md) - Rebuild the Poppy config file from the tenant
+- [auth0 poppy doctor](auth0_poppy_doctor.md) - Check the Poppy discovery chain end to end
+- [auth0 poppy setup](auth0_poppy_setup.md) - Turn on Poppy for the tenant, an API and a web app
+
+