From 3f7876c816f39c9c55ec1d262f589a59ec715078 Mon Sep 17 00:00:00 2001 From: Kristin Brown Date: Fri, 28 Aug 2026 12:23:19 -0400 Subject: [PATCH 1/3] Added reference doc workflow Signed-off-by: Kristin Brown --- .docs-test.toml | 37 ++ .github/workflows/reference-docs.yml | 116 +++- .gitignore | 1 + content/docs/reference/cli/arctl-apply.md | 19 +- content/docs/reference/cli/arctl-build.md | 17 +- .../reference/cli/arctl-completion-bash.md | 56 ++ .../reference/cli/arctl-completion-fish.md | 47 ++ .../cli/arctl-completion-powershell.md | 42 ++ .../reference/cli/arctl-completion-zsh.md | 60 ++ .../docs/reference/cli/arctl-completion.md | 101 +-- .../cli/arctl-configure-claude-code.md | 35 + .../reference/cli/arctl-configure-cursor.md | 35 + .../reference/cli/arctl-configure-kiro.md | 35 + .../reference/cli/arctl-configure-vscode.md | 35 + content/docs/reference/cli/arctl-configure.md | 37 +- .../reference/cli/arctl-db-migrate-down.md | 34 + .../reference/cli/arctl-db-migrate-force.md | 32 + .../reference/cli/arctl-db-migrate-goto.md | 30 + .../reference/cli/arctl-db-migrate-status.md | 34 + .../docs/reference/cli/arctl-db-migrate-up.md | 34 + .../reference/cli/arctl-db-migrate-version.md | 31 + .../docs/reference/cli/arctl-db-migrate.md | 80 +-- content/docs/reference/cli/arctl-db.md | 21 +- content/docs/reference/cli/arctl-delete.md | 25 +- content/docs/reference/cli/arctl-get.md | 27 +- .../docs/reference/cli/arctl-init-agent.md | 24 +- content/docs/reference/cli/arctl-init-mcp.md | 24 +- .../docs/reference/cli/arctl-init-prompt.md | 19 +- .../docs/reference/cli/arctl-init-skill.md | 19 +- content/docs/reference/cli/arctl-init.md | 40 +- content/docs/reference/cli/arctl-pull.md | 15 +- content/docs/reference/cli/arctl-run.md | 37 +- content/docs/reference/cli/arctl-version.md | 16 +- content/docs/reference/cli/arctl-wait.md | 30 +- content/docs/reference/cli/arctl.md | 33 + go.mod | 2 +- go.sum | 10 +- hugo_stats.json | 34 +- scripts/generate-arctl-ref.py | 605 ++++++++++++++++++ 39 files changed, 1599 insertions(+), 330 deletions(-) create mode 100644 content/docs/reference/cli/arctl-completion-bash.md create mode 100644 content/docs/reference/cli/arctl-completion-fish.md create mode 100644 content/docs/reference/cli/arctl-completion-powershell.md create mode 100644 content/docs/reference/cli/arctl-completion-zsh.md create mode 100644 content/docs/reference/cli/arctl-configure-claude-code.md create mode 100644 content/docs/reference/cli/arctl-configure-cursor.md create mode 100644 content/docs/reference/cli/arctl-configure-kiro.md create mode 100644 content/docs/reference/cli/arctl-configure-vscode.md create mode 100644 content/docs/reference/cli/arctl-db-migrate-down.md create mode 100644 content/docs/reference/cli/arctl-db-migrate-force.md create mode 100644 content/docs/reference/cli/arctl-db-migrate-goto.md create mode 100644 content/docs/reference/cli/arctl-db-migrate-status.md create mode 100644 content/docs/reference/cli/arctl-db-migrate-up.md create mode 100644 content/docs/reference/cli/arctl-db-migrate-version.md create mode 100644 content/docs/reference/cli/arctl.md create mode 100644 scripts/generate-arctl-ref.py diff --git a/.docs-test.toml b/.docs-test.toml index acd71a9..ef08230 100644 --- a/.docs-test.toml +++ b/.docs-test.toml @@ -53,6 +53,18 @@ consoleErrors = [ # "invalid_request" pageerror with no stack. Not fixable without a live # backend — suppress until those scripts are refactored to not throw on init. "invalid_request", + # Qualified's chat widget posts to its own sentry proxy on every page load, so + # a site-wide crawl fires one request per page within a few seconds and trips + # that endpoint's rate limit. Whichever pages land after the limit then fail + # with a 429, which makes the failing set shift run to run (48/16/17/0 failures + # across four runs of the same suite) and reads as a content regression when it + # is a property of the crawl's request rate. Scoped to the status AND the host + # so a genuine 429 from our own origin still fails the check. + # + # TEMPORARY: this suppresses the error but the request still fires. The real + # fix is to block third-party hosts at the network layer during the crawl — + # see solo-io/docs-theme-extras#39. Remove this entry once that lands. + "status of 429 .*app\\.qualified\\.com", # NOTE: agr previously allowlisted two Hextra main.min.js null-dereferences # (reading 'removeAttribute' / 'addEventListener') that fired on pages with no # real sidebar (e.g. the /docs/ landing page), where main.js can't find the @@ -64,3 +76,28 @@ consoleErrors = [ # (and in the static "Hextra hamburger toggle target" guard in docs-theme-extras). # Ported from the same fix in agw-oss. ] + +# Builds this source tree is rendered under, for the gateAxisCollision lint. +# +# `conditional-text` gates on two axes — the build condition and the page's +# section segment — through one token namespace, so a token naming a section on +# one axis and a product on the other is true twice and both sides of an +# intended either/or render. +# +# THIS SITE'S OWN BUILD CANNOT FIRE A GATE AT ALL. It registers no +# `params.sections`, and in `url` mode utils/page-context.html assigns a +# condition only when the path carries a section AND a version — with no +# sections registered that never happens, so the condition is always "" and +# conditional-text emits nothing. Consistent with the corpus: it uses no gates +# today. +# +# The docs hub ships an agentregistry product (buildCondition "agentregistry"), +# but its module import of this repo is still commented out, so nothing here is +# rendered under that condition yet. The entry below is staged for when it is: +# once the import is enabled, a gate written here starts resolving downstream +# while staying inert upstream, which is precisely the asymmetry this lint +# catches. +[[gateAxes]] +name = "docs-hub / agentregistry" +condition = "agentregistry" +sections = [] diff --git a/.github/workflows/reference-docs.yml b/.github/workflows/reference-docs.yml index afe646d..62f5686 100644 --- a/.github/workflows/reference-docs.yml +++ b/.github/workflows/reference-docs.yml @@ -1,30 +1,112 @@ -name: Generate CLI Reference +# Regenerates the arctl CLI reference from the agentregistry product repo and +# opens a PR with the result. +# +# Everything lives on this side: scripts/generate-arctl-ref.py builds a +# throwaway Go module that imports arctl's exported command tree through a +# `replace` directive against a plain checkout, runs cobra's doc generator, and +# rewrites the result into Hugo pages. agentregistry needs no changes to support +# this, and cobra/doc's markdown dependencies stay out of its go.mod. +# +# agentregistry docs are unversioned — one flat content tree — so unlike the +# equivalent agentgateway workflow there is no version matrix here. +name: Reference docs on: - push: - branches: [ main ] - paths: - - 'internal/cli/**' # Only run if CLI code changes + schedule: + # Nightly at 06:00 UTC, so published docs don't drift from merged CLI changes. + - cron: '0 6 * * *' + workflow_dispatch: + inputs: + agentregistry_ref: + description: 'agentregistry ref to generate from (branch, tag, or SHA)' + required: false + default: 'main' + +# Queue overlapping runs (nightly cron plus a manual dispatch) rather than +# letting them force-push the same PR branch concurrently. +concurrency: + group: reference-docs + cancel-in-progress: false + +# create-pull-request pushes a branch and opens a PR, so the token needs write +# on both. Without this the token is read-only and the push fails with a 403. +# +# The PR is authored by github-actions[bot], which requires the repo setting +# "Allow GitHub Actions to create and approve pull requests". A consequence is +# that pull_request workflows (framework-tests, links) are queued on the +# generated PR but held as "action_required" — click "Approve and run" on the +# PR's checks to execute them. +permissions: + contents: write + pull-requests: write jobs: - docs: + arctl-reference: + name: Generate arctl CLI reference runs-on: ubuntu-latest + timeout-minutes: 20 steps: - - name: Checkout code - uses: actions/checkout@v4 + - name: Check out the website + uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 with: - fetch-depth: 0 + path: website + + - name: Check out agentregistry + uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 + with: + repository: agentregistry-dev/agentregistry + ref: ${{ inputs.agentregistry_ref || 'main' }} + path: agentregistry + + - name: Record the agentregistry revision + id: source + working-directory: agentregistry + run: echo "sha=$(git rev-parse --short HEAD)" >> "$GITHUB_OUTPUT" - name: Set up Go - uses: actions/setup-go@v5 + uses: actions/setup-go@4b73464bb391d4059bd26b0524d20df3927bd417 # v6.3.0 with: - go-version: '1.22' # Match your project version + go-version-file: agentregistry/go.mod + cache: false - - name: Generate Markdown Docs - run: go run scripts/docgen.go + - name: Generate the arctl reference + env: + WEBSITE_DIR: website + AGENTREGISTRY_DIR: agentregistry + run: python3 website/scripts/generate-arctl-ref.py - - name: Commit and Push changes - uses: stefanzweifel/git-auto-commit-action@v5 + - name: Open a PR + id: pr + uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1 # v8.1.1 with: - commit_message: "docs: auto-generate CLI reference" - file_pattern: 'content/docs/reference/cli/*.md' \ No newline at end of file + path: website + base: main + branch: ref-docs-arctl + delete-branch: true + title: '[Automated] Update the arctl CLI reference' + commit-message: | + docs: regenerate the arctl CLI reference from agentregistry ${{ steps.source.outputs.sha }} + + Signed-off-by: GitHub Action + committer: GitHub Action + body: | + Regenerated the arctl CLI reference from + [`${{ steps.source.outputs.sha }}`](https://github.com/agentregistry-dev/agentregistry/commit/${{ steps.source.outputs.sha }}). + + Every page under `content/docs/reference/cli/` is generated, front matter + included. Edit the cobra command definitions upstream rather than these + files — the next run overwrites anything changed by hand. + + Opened automatically by the [Reference docs workflow](https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}). + labels: | + documentation + automated pr + token: ${{ secrets.GITHUB_TOKEN }} + + - name: Report the result + run: | + if [ -n "${{ steps.pr.outputs.pull-request-url }}" ]; then + echo "PR: ${{ steps.pr.outputs.pull-request-url }}" + else + echo "The reference is already up to date; no PR opened." + fi diff --git a/.gitignore b/.gitignore index 510e1a8..3ea0fe1 100644 --- a/.gitignore +++ b/.gitignore @@ -34,3 +34,4 @@ yarn.lock # Backup directory nextjs-backup/ +scripts/__pycache__/ diff --git a/content/docs/reference/cli/arctl-apply.md b/content/docs/reference/cli/arctl-apply.md index d85ab76..cf6873e 100644 --- a/content/docs/reference/cli/arctl-apply.md +++ b/content/docs/reference/cli/arctl-apply.md @@ -1,12 +1,16 @@ --- title: arctl apply -description: "Apply one or more registry resources from a YAML file." weight: 10 +description: "Apply one or more registry resources from a YAML file." --- -Apply reads a YAML file (or stdin with `-f -`) containing one or more resource documents and applies them via `POST /v0/apply`. + + +Apply reads a YAML file (or stdin with -f -) containing one or more resource +documents and applies them via `POST /v0/apply`. -Each resource is applied atomically; the server reports per-resource status. Errors are reported per resource without aborting the batch. +Each resource is applied atomically; the server reports per-resource status. +Best-effort: per-resource errors are reported without aborting the batch. ## Usage @@ -15,6 +19,7 @@ arctl apply -f FILE [flags] ``` Examples: + ```sh arctl apply -f agent.yaml arctl apply -f stack.yaml --dry-run @@ -24,8 +29,8 @@ cat stack.yaml | arctl apply -f - ## Command-specific flags ```sh ---dry-run Validate and simulate without mutating state --f, --filename strings YAML file to apply (repeatable; use - for stdin) + --dry-run Validate and simulate without mutating state +-f, --filename stringArray YAML file to apply (repeatable; use - for stdin) ``` ## Global flags @@ -35,3 +40,7 @@ cat stack.yaml | arctl apply -f - --registry-token string Registry bearer token (defaults to value of ARCTL_API_TOKEN env var) --registry-url string Registry URL (overrides ARCTL_API_BASE_URL env var; defaults to http://localhost:12121) ``` + +## See also + +* [arctl](../arctl/) - Agent Registry CLI diff --git a/content/docs/reference/cli/arctl-build.md b/content/docs/reference/cli/arctl-build.md index d618058..899ad03 100644 --- a/content/docs/reference/cli/arctl-build.md +++ b/content/docs/reference/cli/arctl-build.md @@ -1,14 +1,18 @@ --- title: arctl build -description: "Build a Docker image for a declarative resource project." weight: 10 +description: "Build a Docker image for a declarative resource project." --- + + Build the Docker image for a project created with `arctl init`. -Reads `arctl.yaml` in the project directory to look up the matching framework by `(framework, language)` and dispatches to its build command. The image tag is taken from the declarative YAML's spec, or from the `--image` override. +Reads `arctl.yaml` in the project directory to look up the matching framework +by (framework, language) and dispatches to its build command. Image tag is taken +from the declarative YAML's spec (or `--image` override). -Supported resource kinds: `Agent`, `MCPServer` +Supported kinds: `Agent`, `MCPServer` ## Usage @@ -17,10 +21,11 @@ arctl build DIRECTORY [flags] ``` Examples: + ```sh arctl build ./my-agent arctl build ./my-server --push -arctl build ./my-agent --image ghcr.io/acme/my-agent:v1.0.0 --platform linux/amd64 +arctl build ./my-agent --image ghcr.io/acme/my-agent:v1.0.0 --platform linux/amd64 ``` ## Command-specific flags @@ -38,3 +43,7 @@ arctl build ./my-agent --image ghcr.io/acme/my-agent:v1.0.0 --platform linux/amd --registry-token string Registry bearer token (defaults to value of ARCTL_API_TOKEN env var) --registry-url string Registry URL (overrides ARCTL_API_BASE_URL env var; defaults to http://localhost:12121) ``` + +## See also + +* [arctl](../arctl/) - Agent Registry CLI diff --git a/content/docs/reference/cli/arctl-completion-bash.md b/content/docs/reference/cli/arctl-completion-bash.md new file mode 100644 index 0000000..aa20c8d --- /dev/null +++ b/content/docs/reference/cli/arctl-completion-bash.md @@ -0,0 +1,56 @@ +--- +title: arctl completion bash +weight: 10 +description: "Generate the autocompletion script for bash." +--- + + + +Generate the autocompletion script for the bash shell. + +This script depends on the `bash-completion` package. +If it is not installed already, you can install it via your OS's package manager. + +To load completions in your current shell session: + +```sh +source <(arctl completion bash) +``` + +To load completions for every new session, execute once: + +**Linux:** +```sh +arctl completion bash > /etc/bash_completion.d/arctl +``` + +**macOS:** +```sh +arctl completion bash > $(brew --prefix)/etc/bash_completion.d/arctl +``` + +You will need to start a new shell for this setup to take effect. + +## Usage + +```sh +arctl completion bash +``` + +## Command-specific flags + +```sh + --no-descriptions disable completion descriptions +``` + +## Global flags + +```sh +-h, --help Display help information for the command. + --registry-token string Registry bearer token (defaults to value of ARCTL_API_TOKEN env var) + --registry-url string Registry URL (overrides ARCTL_API_BASE_URL env var; defaults to http://localhost:12121) +``` + +## See also + +* [arctl completion](../arctl-completion/) - Generate the autocompletion script for the specified shell diff --git a/content/docs/reference/cli/arctl-completion-fish.md b/content/docs/reference/cli/arctl-completion-fish.md new file mode 100644 index 0000000..4eff580 --- /dev/null +++ b/content/docs/reference/cli/arctl-completion-fish.md @@ -0,0 +1,47 @@ +--- +title: arctl completion fish +weight: 10 +description: "Generate the autocompletion script for fish." +--- + + + +Generate the autocompletion script for the fish shell. + +To load completions in your current shell session: + +```sh +arctl completion fish | source +``` + +To load completions for every new session, execute once: + +```sh +arctl completion fish > ~/.config/fish/completions/arctl.fish +``` + +You will need to start a new shell for this setup to take effect. + +## Usage + +```sh +arctl completion fish [flags] +``` + +## Command-specific flags + +```sh + --no-descriptions disable completion descriptions +``` + +## Global flags + +```sh +-h, --help Display help information for the command. + --registry-token string Registry bearer token (defaults to value of ARCTL_API_TOKEN env var) + --registry-url string Registry URL (overrides ARCTL_API_BASE_URL env var; defaults to http://localhost:12121) +``` + +## See also + +* [arctl completion](../arctl-completion/) - Generate the autocompletion script for the specified shell diff --git a/content/docs/reference/cli/arctl-completion-powershell.md b/content/docs/reference/cli/arctl-completion-powershell.md new file mode 100644 index 0000000..726b689 --- /dev/null +++ b/content/docs/reference/cli/arctl-completion-powershell.md @@ -0,0 +1,42 @@ +--- +title: arctl completion powershell +weight: 10 +description: "Generate the autocompletion script for powershell." +--- + + + +Generate the autocompletion script for powershell. + +To load completions in your current shell session: + +```sh +arctl completion powershell | Out-String | Invoke-Expression +``` + +To load completions for every new session, add the output of the above command +to your powershell profile. + +## Usage + +```sh +arctl completion powershell [flags] +``` + +## Command-specific flags + +```sh + --no-descriptions disable completion descriptions +``` + +## Global flags + +```sh +-h, --help Display help information for the command. + --registry-token string Registry bearer token (defaults to value of ARCTL_API_TOKEN env var) + --registry-url string Registry URL (overrides ARCTL_API_BASE_URL env var; defaults to http://localhost:12121) +``` + +## See also + +* [arctl completion](../arctl-completion/) - Generate the autocompletion script for the specified shell diff --git a/content/docs/reference/cli/arctl-completion-zsh.md b/content/docs/reference/cli/arctl-completion-zsh.md new file mode 100644 index 0000000..a498191 --- /dev/null +++ b/content/docs/reference/cli/arctl-completion-zsh.md @@ -0,0 +1,60 @@ +--- +title: arctl completion zsh +weight: 10 +description: "Generate the autocompletion script for zsh." +--- + + + +Generate the autocompletion script for the zsh shell. + +If shell completion is not already enabled in your environment you will need +to enable it. You can execute the following once: + +```sh +echo "autoload -U compinit; compinit" >> ~/.zshrc +``` + +To load completions in your current shell session: + +```sh +source <(arctl completion zsh) +``` + +To load completions for every new session, execute once: + +**Linux:** +```sh +arctl completion zsh > "${fpath[1]}/_arctl" +``` + +**macOS:** +```sh +arctl completion zsh > $(brew --prefix)/share/zsh/site-functions/_arctl +``` + +You will need to start a new shell for this setup to take effect. + +## Usage + +```sh +arctl completion zsh [flags] +``` + +## Command-specific flags + +```sh + --no-descriptions disable completion descriptions +``` + +## Global flags + +```sh +-h, --help Display help information for the command. + --registry-token string Registry bearer token (defaults to value of ARCTL_API_TOKEN env var) + --registry-url string Registry URL (overrides ARCTL_API_BASE_URL env var; defaults to http://localhost:12121) +``` + +## See also + +* [arctl completion](../arctl-completion/) - Generate the autocompletion script for the specified shell diff --git a/content/docs/reference/cli/arctl-completion.md b/content/docs/reference/cli/arctl-completion.md index cd08829..6263cd9 100644 --- a/content/docs/reference/cli/arctl-completion.md +++ b/content/docs/reference/cli/arctl-completion.md @@ -1,98 +1,13 @@ --- title: arctl completion -description: "Generate shell autocompletion scripts for arctl." weight: 10 +description: "Generate the autocompletion script for the specified shell." --- -Generate the autocompletion script for `arctl` for the specified shell. + -## Usage - -```sh -arctl completion [command] -``` - -Available sub-commands: `bash`, `fish`, `powershell`, `zsh` - -## bash - -```sh -arctl completion bash -``` - -To load completions in your current shell session: -```sh -source <(arctl completion bash) -``` - -To load completions for every new session (execute once): -```sh -# Linux: -arctl completion bash > /etc/bash_completion.d/arctl - -# macOS: -arctl completion bash > $(brew --prefix)/etc/bash_completion.d/arctl -``` - -## fish - -```sh -arctl completion fish -``` - -To load completions in your current shell session: -```sh -arctl completion fish | source -``` - -To load completions for every new session (execute once): -```sh -arctl completion fish > ~/.config/fish/completions/arctl.fish -``` - -## powershell - -```sh -arctl completion powershell -``` - -To load completions in your current shell session: -```sh -arctl completion powershell | Out-String | Invoke-Expression -``` - -To load completions for every new session, add the output of the above command to your PowerShell profile. - -## zsh - -```sh -arctl completion zsh -``` - -To enable shell completion (execute once): -```sh -echo "autoload -U compinit; compinit" >> ~/.zshrc -``` - -To load completions in your current shell session: -```sh -source <(arctl completion zsh) -``` - -To load completions for every new session (execute once): -```sh -# Linux: -arctl completion zsh > "${fpath[1]}/_arctl" - -# macOS: -arctl completion zsh > $(brew --prefix)/share/zsh/site-functions/_arctl -``` - -## Command-specific flags - -```sh - --no-descriptions Disable completion descriptions -``` +Generate the autocompletion script for arctl for the specified shell. +See each sub-command's help for details on how to use the generated script. ## Global flags @@ -101,3 +16,11 @@ arctl completion zsh > $(brew --prefix)/share/zsh/site-functions/_arctl --registry-token string Registry bearer token (defaults to value of ARCTL_API_TOKEN env var) --registry-url string Registry URL (overrides ARCTL_API_BASE_URL env var; defaults to http://localhost:12121) ``` + +## See also + +* [arctl](../arctl/) - Agent Registry CLI +* [arctl completion bash](../arctl-completion-bash/) - Generate the autocompletion script for bash +* [arctl completion fish](../arctl-completion-fish/) - Generate the autocompletion script for fish +* [arctl completion powershell](../arctl-completion-powershell/) - Generate the autocompletion script for powershell +* [arctl completion zsh](../arctl-completion-zsh/) - Generate the autocompletion script for zsh diff --git a/content/docs/reference/cli/arctl-configure-claude-code.md b/content/docs/reference/cli/arctl-configure-claude-code.md new file mode 100644 index 0000000..505d02e --- /dev/null +++ b/content/docs/reference/cli/arctl-configure-claude-code.md @@ -0,0 +1,35 @@ +--- +title: arctl configure claude-code +weight: 10 +description: "Configure Claude Code." +--- + + + +Configure Claude Code + +## Usage + +```sh +arctl configure claude-code [flags] +``` + +## Command-specific flags + +```sh + --port string Port for the MCP server (default "21212") + --token-env string Name of the environment variable holding the MCP bearer token for static/direct access (e.g. ARCTL_MCP_TOKEN); written into the config as a reference the client expands at connect time. Clients that support OAuth can authenticate interactively instead, without this flag + --url string Custom MCP server URL (default: http://localhost:21212/mcp) +``` + +## Global flags + +```sh +-h, --help Display help information for the command. + --registry-token string Registry bearer token (defaults to value of ARCTL_API_TOKEN env var) + --registry-url string Registry URL (overrides ARCTL_API_BASE_URL env var; defaults to http://localhost:12121) +``` + +## See also + +* [arctl configure](../arctl-configure/) - Create the JSON configuration a client needs to connect to arctl diff --git a/content/docs/reference/cli/arctl-configure-cursor.md b/content/docs/reference/cli/arctl-configure-cursor.md new file mode 100644 index 0000000..c713966 --- /dev/null +++ b/content/docs/reference/cli/arctl-configure-cursor.md @@ -0,0 +1,35 @@ +--- +title: arctl configure cursor +weight: 10 +description: "Configure Cursor AI Editor." +--- + + + +Configure Cursor AI Editor + +## Usage + +```sh +arctl configure cursor [flags] +``` + +## Command-specific flags + +```sh + --port string Port for the MCP server (default "21212") + --token-env string Name of the environment variable holding the MCP bearer token for static/direct access (e.g. ARCTL_MCP_TOKEN); written into the config as a reference the client expands at connect time. Clients that support OAuth can authenticate interactively instead, without this flag + --url string Custom MCP server URL (default: http://localhost:21212/mcp) +``` + +## Global flags + +```sh +-h, --help Display help information for the command. + --registry-token string Registry bearer token (defaults to value of ARCTL_API_TOKEN env var) + --registry-url string Registry URL (overrides ARCTL_API_BASE_URL env var; defaults to http://localhost:12121) +``` + +## See also + +* [arctl configure](../arctl-configure/) - Create the JSON configuration a client needs to connect to arctl diff --git a/content/docs/reference/cli/arctl-configure-kiro.md b/content/docs/reference/cli/arctl-configure-kiro.md new file mode 100644 index 0000000..47aa2fc --- /dev/null +++ b/content/docs/reference/cli/arctl-configure-kiro.md @@ -0,0 +1,35 @@ +--- +title: arctl configure kiro +weight: 10 +description: "Configure Kiro agentic IDE." +--- + + + +Configure Kiro agentic IDE + +## Usage + +```sh +arctl configure kiro [flags] +``` + +## Command-specific flags + +```sh + --port string Port for the MCP server (default "21212") + --token-env string Name of the environment variable holding the MCP bearer token for static/direct access (e.g. ARCTL_MCP_TOKEN); written into the config as a reference the client expands at connect time. Clients that support OAuth can authenticate interactively instead, without this flag + --url string Custom MCP server URL (default: http://localhost:21212/mcp) +``` + +## Global flags + +```sh +-h, --help Display help information for the command. + --registry-token string Registry bearer token (defaults to value of ARCTL_API_TOKEN env var) + --registry-url string Registry URL (overrides ARCTL_API_BASE_URL env var; defaults to http://localhost:12121) +``` + +## See also + +* [arctl configure](../arctl-configure/) - Create the JSON configuration a client needs to connect to arctl diff --git a/content/docs/reference/cli/arctl-configure-vscode.md b/content/docs/reference/cli/arctl-configure-vscode.md new file mode 100644 index 0000000..9682464 --- /dev/null +++ b/content/docs/reference/cli/arctl-configure-vscode.md @@ -0,0 +1,35 @@ +--- +title: arctl configure vscode +weight: 10 +description: "Configure Visual Studio Code." +--- + + + +Configure Visual Studio Code + +## Usage + +```sh +arctl configure vscode [flags] +``` + +## Command-specific flags + +```sh + --port string Port for the MCP server (default "21212") + --token-env string Name of the environment variable holding the MCP bearer token for static/direct access (e.g. ARCTL_MCP_TOKEN); written into the config as a reference the client expands at connect time. Clients that support OAuth can authenticate interactively instead, without this flag + --url string Custom MCP server URL (default: http://localhost:21212/mcp) +``` + +## Global flags + +```sh +-h, --help Display help information for the command. + --registry-token string Registry bearer token (defaults to value of ARCTL_API_TOKEN env var) + --registry-url string Registry URL (overrides ARCTL_API_BASE_URL env var; defaults to http://localhost:12121) +``` + +## See also + +* [arctl configure](../arctl-configure/) - Create the JSON configuration a client needs to connect to arctl diff --git a/content/docs/reference/cli/arctl-configure.md b/content/docs/reference/cli/arctl-configure.md index cc8b313..478e5e6 100644 --- a/content/docs/reference/cli/arctl-configure.md +++ b/content/docs/reference/cli/arctl-configure.md @@ -1,35 +1,12 @@ --- title: arctl configure -description: "Create the JSON configuration each client needs to connect to arctl." weight: 10 +description: "Create the JSON configuration a client needs to connect to arctl." --- -Creates the `.json` configuration for each client, so it can connect to `arctl`. + -Clients that support OAuth can authenticate interactively without using `--token-env`. For static or direct access, pass `--token-env` with the name of the environment variable holding the MCP bearer token. - -## Usage - -```sh -arctl configure [client-name] [flags] -``` - -Examples: -```sh -arctl configure claude-desktop -arctl configure my-client --url http://localhost:21212/mcp --port 21212 -arctl configure my-client --token-env ARCTL_MCP_TOKEN -``` - -## Command-specific flags - -```sh - --port string Port for the MCP server (default "21212") - --token-env string Name of the environment variable holding the MCP bearer token for static/direct access - (e.g. ARCTL_MCP_TOKEN); written into the config as a reference the client expands at - connect time. Clients that support OAuth can authenticate interactively instead. - --url string Custom MCP server URL (default: http://localhost:21212/mcp) -``` +Creates the .json configuration for each client, so it can connect to arctl. ## Global flags @@ -38,3 +15,11 @@ arctl configure my-client --token-env ARCTL_MCP_TOKEN --registry-token string Registry bearer token (defaults to value of ARCTL_API_TOKEN env var) --registry-url string Registry URL (overrides ARCTL_API_BASE_URL env var; defaults to http://localhost:12121) ``` + +## See also + +* [arctl](../arctl/) - Agent Registry CLI +* [arctl configure claude-code](../arctl-configure-claude-code/) - Configure Claude Code +* [arctl configure cursor](../arctl-configure-cursor/) - Configure Cursor AI Editor +* [arctl configure kiro](../arctl-configure-kiro/) - Configure Kiro agentic IDE +* [arctl configure vscode](../arctl-configure-vscode/) - Configure Visual Studio Code diff --git a/content/docs/reference/cli/arctl-db-migrate-down.md b/content/docs/reference/cli/arctl-db-migrate-down.md new file mode 100644 index 0000000..f82d53a --- /dev/null +++ b/content/docs/reference/cli/arctl-db-migrate-down.md @@ -0,0 +1,34 @@ +--- +title: arctl db migrate down +weight: 10 +description: "Roll back the N most-recent applied migrations for the selected source." +--- + + + +Roll back the `N` most-recent applied migrations for the selected source. + +Migrations whose .down.sql raises (up-only / not-reversible migrations) +will leave the `schema_migrations` row marked dirty after the failed +rollback. Subsequent `up` invocations will refuse to run until the +dirty marker is cleared with 'arctl db migrate force V', where V is +the version named in the failure message. + +## Usage + +```sh +arctl db migrate down N [flags] +``` + +## Global flags + +```sh +-h, --help Display help information for the command. + --db-url string PostgreSQL connection URL (defaults to value of AGENT_REGISTRY_DATABASE_URL env var) + --registry-token string Registry bearer token (defaults to value of ARCTL_API_TOKEN env var) + --registry-url string Registry URL (overrides ARCTL_API_BASE_URL env var; defaults to http://localhost:12121) +``` + +## See also + +* [arctl db migrate](../arctl-db-migrate/) - Apply, roll back, and inspect database migrations diff --git a/content/docs/reference/cli/arctl-db-migrate-force.md b/content/docs/reference/cli/arctl-db-migrate-force.md new file mode 100644 index 0000000..ce0f4fc --- /dev/null +++ b/content/docs/reference/cli/arctl-db-migrate-force.md @@ -0,0 +1,32 @@ +--- +title: arctl db migrate force +weight: 10 +description: "Mark version V as applied without running its SQL." +--- + + + +Used to reconcile the selected source's `schema_migrations` table +after manual remediation. The version `V` should come from a prior +failure message and must correspond to a shipped migration file in +the selected source — otherwise the `schema_migrations` row would point +at a version the binary cannot apply or roll back to, wedging the DB. + +## Usage + +```sh +arctl db migrate force V [flags] +``` + +## Global flags + +```sh +-h, --help Display help information for the command. + --db-url string PostgreSQL connection URL (defaults to value of AGENT_REGISTRY_DATABASE_URL env var) + --registry-token string Registry bearer token (defaults to value of ARCTL_API_TOKEN env var) + --registry-url string Registry URL (overrides ARCTL_API_BASE_URL env var; defaults to http://localhost:12121) +``` + +## See also + +* [arctl db migrate](../arctl-db-migrate/) - Apply, roll back, and inspect database migrations diff --git a/content/docs/reference/cli/arctl-db-migrate-goto.md b/content/docs/reference/cli/arctl-db-migrate-goto.md new file mode 100644 index 0000000..9e14f9b --- /dev/null +++ b/content/docs/reference/cli/arctl-db-migrate-goto.md @@ -0,0 +1,30 @@ +--- +title: arctl db migrate goto +weight: 10 +description: "Move the selected source's schema to version V." +--- + + + +Move the selected source's schema to version `V` (forward or backward). +`V`=0 is the special "empty schema" target: every applied migration in +the source is rolled back. + +## Usage + +```sh +arctl db migrate goto V [flags] +``` + +## Global flags + +```sh +-h, --help Display help information for the command. + --db-url string PostgreSQL connection URL (defaults to value of AGENT_REGISTRY_DATABASE_URL env var) + --registry-token string Registry bearer token (defaults to value of ARCTL_API_TOKEN env var) + --registry-url string Registry URL (overrides ARCTL_API_BASE_URL env var; defaults to http://localhost:12121) +``` + +## See also + +* [arctl db migrate](../arctl-db-migrate/) - Apply, roll back, and inspect database migrations diff --git a/content/docs/reference/cli/arctl-db-migrate-status.md b/content/docs/reference/cli/arctl-db-migrate-status.md new file mode 100644 index 0000000..7a3591e --- /dev/null +++ b/content/docs/reference/cli/arctl-db-migrate-status.md @@ -0,0 +1,34 @@ +--- +title: arctl db migrate status +weight: 10 +description: "Show how many migrations are applied vs pending across all sources." +--- + + + +Show how many migrations are applied vs pending across all sources + +## Usage + +```sh +arctl db migrate status [flags] +``` + +## Command-specific flags + +```sh +-o, --output string Output format: "text" (default) or "json" (default "text") +``` + +## Global flags + +```sh +-h, --help Display help information for the command. + --db-url string PostgreSQL connection URL (defaults to value of AGENT_REGISTRY_DATABASE_URL env var) + --registry-token string Registry bearer token (defaults to value of ARCTL_API_TOKEN env var) + --registry-url string Registry URL (overrides ARCTL_API_BASE_URL env var; defaults to http://localhost:12121) +``` + +## See also + +* [arctl db migrate](../arctl-db-migrate/) - Apply, roll back, and inspect database migrations diff --git a/content/docs/reference/cli/arctl-db-migrate-up.md b/content/docs/reference/cli/arctl-db-migrate-up.md new file mode 100644 index 0000000..e629e96 --- /dev/null +++ b/content/docs/reference/cli/arctl-db-migrate-up.md @@ -0,0 +1,34 @@ +--- +title: arctl db migrate up +weight: 10 +description: "Apply all pending migrations across every registered source." +--- + + + +Applies pending migrations for every registered source in +registration order. Per source, the orchestrator acquires a +`pg_advisory_lock` so concurrent pods serialize, then runs +Steps(1) → LegacyRun (if defined) → Up(). + +The `--source` flag is intentionally not applicable to up; pass it only +on the per-source subcommands (down/goto/force). + +## Usage + +```sh +arctl db migrate up [flags] +``` + +## Global flags + +```sh +-h, --help Display help information for the command. + --db-url string PostgreSQL connection URL (defaults to value of AGENT_REGISTRY_DATABASE_URL env var) + --registry-token string Registry bearer token (defaults to value of ARCTL_API_TOKEN env var) + --registry-url string Registry URL (overrides ARCTL_API_BASE_URL env var; defaults to http://localhost:12121) +``` + +## See also + +* [arctl db migrate](../arctl-db-migrate/) - Apply, roll back, and inspect database migrations diff --git a/content/docs/reference/cli/arctl-db-migrate-version.md b/content/docs/reference/cli/arctl-db-migrate-version.md new file mode 100644 index 0000000..f1fb8ad --- /dev/null +++ b/content/docs/reference/cli/arctl-db-migrate-version.md @@ -0,0 +1,31 @@ +--- +title: arctl db migrate version +weight: 10 +description: "Print the highest applied migration version." +--- + + + +Print the highest applied migration version. +For a single registered source the value is on one line; multi-source +binaries print one line per source. When multiple sources are +registered, `--source` filters to a single track. + +## Usage + +```sh +arctl db migrate version [flags] +``` + +## Global flags + +```sh +-h, --help Display help information for the command. + --db-url string PostgreSQL connection URL (defaults to value of AGENT_REGISTRY_DATABASE_URL env var) + --registry-token string Registry bearer token (defaults to value of ARCTL_API_TOKEN env var) + --registry-url string Registry URL (overrides ARCTL_API_BASE_URL env var; defaults to http://localhost:12121) +``` + +## See also + +* [arctl db migrate](../arctl-db-migrate/) - Apply, roll back, and inspect database migrations diff --git a/content/docs/reference/cli/arctl-db-migrate.md b/content/docs/reference/cli/arctl-db-migrate.md index c372ed3..d6c39d1 100644 --- a/content/docs/reference/cli/arctl-db-migrate.md +++ b/content/docs/reference/cli/arctl-db-migrate.md @@ -1,77 +1,35 @@ --- title: arctl db migrate -description: "Apply, roll back, and inspect database migrations." weight: 10 +description: "Apply, roll back, and inspect database migrations." --- -Apply, roll back, and inspect database migrations independently of server startup. Reads `AGENT_REGISTRY_DATABASE_URL` from the environment when `--db-url` is omitted. - -## Usage - -```sh -arctl db migrate [command] [flags] -``` - -Available sub-commands: `down`, `force`, `goto`, `status`, `up`, `version` - -## db migrate up - -Apply all pending migrations across every registered source. Acquires a `pg_advisory_lock` per source so concurrent pods serialize. - -```sh -arctl db migrate up -``` - -## db migrate down - -Roll back the `N` most-recent applied migrations. - -```sh -arctl db migrate down N -``` - -Migrations whose `.down.sql` raises an error will leave the `schema_migrations` row marked dirty. Use `arctl db migrate force V` to clear the dirty marker after manual remediation. - -## db migrate goto + -Move the schema to version `V` (forward or backward). Use `V=0` to roll back every applied migration. +Apply, roll back, and inspect database migrations independently +of server startup. Reads `AGENT_REGISTRY_DATABASE_URL` from the environment when +`--db-url` is omitted. -```sh -arctl db migrate goto V -``` - -## db migrate force - -Mark version `V` as applied without running its SQL. Use this to reconcile the `schema_migrations` table after manual remediation. The version must correspond to a shipped migration file. - -```sh -arctl db migrate force V -``` - -## db migrate status - -Show how many migrations are applied vs pending across all sources. +## Command-specific flags ```sh -arctl db migrate status [flags] -``` - -Flags: -```sh --o, --output string Output format: "text" (default) or "json" + --db-url string PostgreSQL connection URL (defaults to value of AGENT_REGISTRY_DATABASE_URL env var) ``` -## db migrate version - -Print the highest applied migration version. For a single source the value is on one line; multi-source binaries print one line per source. +## Global flags ```sh -arctl db migrate version +-h, --help Display help information for the command. + --registry-token string Registry bearer token (defaults to value of ARCTL_API_TOKEN env var) + --registry-url string Registry URL (overrides ARCTL_API_BASE_URL env var; defaults to http://localhost:12121) ``` -## Global flags +## See also -```sh - --db-url string PostgreSQL connection URL (defaults to value of AGENT_REGISTRY_DATABASE_URL env var) --h, --help Display help information for the command. -``` +* [arctl db](../arctl-db/) - Database operations for the agent registry (migrations, inspection) +* [arctl db migrate down](../arctl-db-migrate-down/) - Roll back the N most-recent applied migrations for the selected source +* [arctl db migrate force](../arctl-db-migrate-force/) - Mark version V as applied without running its SQL +* [arctl db migrate goto](../arctl-db-migrate-goto/) - Move the selected source's schema to version V +* [arctl db migrate status](../arctl-db-migrate-status/) - Show how many migrations are applied vs pending across all sources +* [arctl db migrate up](../arctl-db-migrate-up/) - Apply all pending migrations across every registered source +* [arctl db migrate version](../arctl-db-migrate-version/) - Print the highest applied migration version diff --git a/content/docs/reference/cli/arctl-db.md b/content/docs/reference/cli/arctl-db.md index 4e90573..e2befbd 100644 --- a/content/docs/reference/cli/arctl-db.md +++ b/content/docs/reference/cli/arctl-db.md @@ -1,21 +1,22 @@ --- title: arctl db -description: "Database operations for the agent registry (migrations, inspection)." weight: 10 +description: "Database operations for the agent registry (migrations, inspection)." --- -Database operations for the agent registry: running, rolling back, and inspecting database migrations. - -## Usage - -```sh -arctl db [command] -``` + -Available sub-commands: `migrate` +Database operations for the agent registry (migrations, inspection) ## Global flags ```sh --h, --help Display help information for the command. +-h, --help Display help information for the command. + --registry-token string Registry bearer token (defaults to value of ARCTL_API_TOKEN env var) + --registry-url string Registry URL (overrides ARCTL_API_BASE_URL env var; defaults to http://localhost:12121) ``` + +## See also + +* [arctl](../arctl/) - Agent Registry CLI +* [arctl db migrate](../arctl-db-migrate/) - Apply, roll back, and inspect database migrations diff --git a/content/docs/reference/cli/arctl-delete.md b/content/docs/reference/cli/arctl-delete.md index b61948b..67ec3bf 100644 --- a/content/docs/reference/cli/arctl-delete.md +++ b/content/docs/reference/cli/arctl-delete.md @@ -1,16 +1,28 @@ --- title: arctl delete -description: "Delete a registry resource by type and name, or from a YAML file." weight: 10 +description: "Delete a registry resource by type and name, or from a YAML file." --- + + Delete a registry resource. -**File mode (declarative):** reads resources from a YAML file and sends `DELETE /v0/apply`. +File mode (declarative): reads resources from the YAML file and sends `DELETE /v0/apply`. + +```sh +arctl delete -f agent.yaml +``` + +Explicit mode: specify type and name. For taggable artifacts, `--tag` selects an +exact tag and defaults to latest. -**Explicit mode:** specify the type and name directly. For taggable artifacts (agents, MCPs, skills, prompts), `--tag` selects an exact tag and defaults to `latest`. +```sh +arctl delete TYPE NAME [--tag TAG] +``` -Supported types: `agent`, `mcp`, `skill`, `prompt`, `deployment` (plural and uppercase forms also accepted) +`TYPE` must be one of: `agent`, `mcp`, `skill`, `prompt`, `deployment` +(plural and uppercase forms also accepted) ## Usage @@ -19,6 +31,7 @@ arctl delete (TYPE NAME | -f FILE) [flags] ``` Examples: + ```sh arctl delete -f my-agent/agent.yaml arctl delete -f my-server/mcp.yaml @@ -43,3 +56,7 @@ arctl delete deployment team-a/my-agent --registry-token string Registry bearer token (defaults to value of ARCTL_API_TOKEN env var) --registry-url string Registry URL (overrides ARCTL_API_BASE_URL env var; defaults to http://localhost:12121) ``` + +## See also + +* [arctl](../arctl/) - Agent Registry CLI diff --git a/content/docs/reference/cli/arctl-get.md b/content/docs/reference/cli/arctl-get.md index 06ae0f3..7cfe7d3 100644 --- a/content/docs/reference/cli/arctl-get.md +++ b/content/docs/reference/cli/arctl-get.md @@ -1,14 +1,15 @@ --- title: arctl get -description: "List or retrieve registry resources by type." weight: 10 +description: "List or retrieve registry resources by type." --- -List or retrieve registry resources by type. + -Supported types: `agents`, `mcps`, `skills`, `prompts`, `runtimes`, `deployments` (singular and uppercase forms also accepted, e.g. `Agent`, `agent`, `agents`) +List or retrieve registry resources by type. -Use `arctl get all` to retrieve resources of every type. +Supported types: `agents`, `mcps`, `skills`, `prompts`, `runtimes`, `deployments` +(singular and uppercase forms also accepted, e.g. `Agent`, `agent`, `agents`) ## Usage @@ -17,9 +18,12 @@ arctl get TYPE [NAME] [flags] ``` Examples: + ```sh arctl get all arctl get agents +arctl get agents -l team=platform,tier=production +arctl get agents --show-labels # list rows with a LABELS column arctl get agents --tag stable # list rows with a specific tag arctl get agents --latest # list rows pinned to the "latest" tag arctl get mcps @@ -37,13 +41,12 @@ arctl get skills -o json ```sh --all-tags List every tag of NAME (tagged content kinds only) - --latest List mode only: restrict to rows pinned to the literal 'latest' tag - (equivalent to --tag latest) - --origin string Deployments only: filter by provenance — managed, discovered, or all - (defaults to managed when unset) +-l, --labels string Content kinds only: filter list rows by comma-separated key=value labels. + --latest List mode only: restrict to rows pinned to the literal 'latest' tag (equivalent to --tag latest). + --origin string Deployments only: filter by provenance — managed, discovered, or all (defaults to managed when unset). -o, --output string Output format: table, yaml, json (default "table") - --tag string Tagged kinds only. With NAME: fetch one tag (defaults to latest). - Without NAME: filter the list to this tag. + --show-labels Print an additional LABELS column with each resource's labels; ignored for -o yaml/json, which already include labels. + --tag string Tagged kinds only. With NAME: fetch one tag (defaults to latest). Without NAME: filter the list to this tag. ``` ## Global flags @@ -53,3 +56,7 @@ arctl get skills -o json --registry-token string Registry bearer token (defaults to value of ARCTL_API_TOKEN env var) --registry-url string Registry URL (overrides ARCTL_API_BASE_URL env var; defaults to http://localhost:12121) ``` + +## See also + +* [arctl](../arctl/) - Agent Registry CLI diff --git a/content/docs/reference/cli/arctl-init-agent.md b/content/docs/reference/cli/arctl-init-agent.md index b4d4ecf..9947b57 100644 --- a/content/docs/reference/cli/arctl-init-agent.md +++ b/content/docs/reference/cli/arctl-init-agent.md @@ -1,17 +1,22 @@ --- title: arctl init agent -description: "Scaffold a new agent project with declarative YAML and framework stubs." weight: 10 +description: "Scaffold a new agent project with declarative YAML and framework stubs." --- + + Scaffold a new agent project. -Picks a framework and language interactively (or via `--framework` / `--language`). Writes: -- `agent.yaml` — `v1alpha1` envelope +Picks a framework + language interactively (or via `--framework` / `--language`). +Writes: +- `agent.yaml` — v1alpha1 envelope - `arctl.yaml` — local build config (framework + language) - `.env` — env vars the chosen framework needs (gitignored) -To wire a sibling `arctl init`'d MCP project for local dev, pass `--local-mcp`. For an MCP at an arbitrary URL (remote or local-not-arctl), edit `.env` after init and add an `MCP_SERVERS_CONFIG` entry: +To wire a sibling arctl-init'd MCP project for local dev, pass `--local-mcp`. +For an MCP at an arbitrary URL (remote, or local-not-arctl), edit `.env` after +init and add an `MCP_SERVERS_CONFIG` entry, e.g.: ```sh MCP_SERVERS_CONFIG=[{"name":"my-remote","type":"remote","url":"https://mcp.example.com/sse"}] @@ -24,6 +29,7 @@ arctl init agent NAME [flags] ``` Examples: + ```sh arctl init agent myagent arctl init agent myagent --framework adk --language python @@ -49,6 +55,12 @@ arctl init agent myagent --local-mcp ../my-mcp ## Global flags ```sh --h, --help Display help information for the command. - --output-dir string Parent directory under which the project is created (defaults to the current directory) +-h, --help Display help information for the command. + --output-dir string Parent directory under which the project is created. Defaults to the current directory. + --registry-token string Registry bearer token (defaults to value of ARCTL_API_TOKEN env var) + --registry-url string Registry URL (overrides ARCTL_API_BASE_URL env var; defaults to http://localhost:12121) ``` + +## See also + +* [arctl init](../arctl-init/) - Scaffold a new declarative resource project (agent, MCP server, skill, or prompt) diff --git a/content/docs/reference/cli/arctl-init-mcp.md b/content/docs/reference/cli/arctl-init-mcp.md index 0f3eb0f..26ea22f 100644 --- a/content/docs/reference/cli/arctl-init-mcp.md +++ b/content/docs/reference/cli/arctl-init-mcp.md @@ -1,14 +1,16 @@ --- title: arctl init mcp -description: "Scaffold a new MCP server project with declarative YAML and framework stubs." weight: 10 +description: "Scaffold a new MCP server project with declarative YAML and framework stubs." --- -Scaffold a new MCP server project. + -Picks a framework and language interactively (or via `--framework` / `--language`). +Scaffold a new MCP server project. -The name must be a DNS-1123 subdomain: lowercase alphanumeric, hyphens, and dots; max 253 chars; each dot-separated segment must start and end with alphanumeric (max 63 chars per segment). +`NAME` must be DNS-1123 subdomain: lowercase alphanumeric, hyphens, and dots; max 253 chars; +each dot-separated segment must start and end with alphanumeric (max 63 chars per segment). +Picks a framework + language interactively (or via `--framework` / `--language`). ## Usage @@ -17,6 +19,7 @@ arctl init mcp NAME [flags] ``` Examples: + ```sh arctl init mcp my-mcp arctl init mcp my-mcp --framework fastmcp --language python @@ -31,13 +34,18 @@ arctl init mcp my-stdio --framework fastmcp --language python --transport stdio --image string Image tag override --language string Language. Skips picker. --port int HTTP port the MCP server binds to (and that arctl run maps) (default 3000) - --transport string MCP transport: "http" (Streamable HTTP, listens on --port) or "stdio" (stdin/stdout). - Defaults to http when omitted. + --transport string MCP transport: "http" (Streamable HTTP, listens on --port) or "stdio" (stdin/stdout). Defaults to http when omitted. ``` ## Global flags ```sh --h, --help Display help information for the command. - --output-dir string Parent directory under which the project is created (defaults to the current directory) +-h, --help Display help information for the command. + --output-dir string Parent directory under which the project is created. Defaults to the current directory. + --registry-token string Registry bearer token (defaults to value of ARCTL_API_TOKEN env var) + --registry-url string Registry URL (overrides ARCTL_API_BASE_URL env var; defaults to http://localhost:12121) ``` + +## See also + +* [arctl init](../arctl-init/) - Scaffold a new declarative resource project (agent, MCP server, skill, or prompt) diff --git a/content/docs/reference/cli/arctl-init-prompt.md b/content/docs/reference/cli/arctl-init-prompt.md index 56cf22d..8510656 100644 --- a/content/docs/reference/cli/arctl-init-prompt.md +++ b/content/docs/reference/cli/arctl-init-prompt.md @@ -1,12 +1,16 @@ --- title: arctl init prompt -description: "Create a new declarative prompt YAML using the ar.dev/v1alpha1 format." weight: 10 +description: "Create a new declarative prompt YAML using the ar.dev/v1alpha1 format." --- -Create a new `.yaml` in the current directory using the `ar.dev/v1alpha1` declarative format. No code scaffolding is generated. + + +Create a new <name>.yaml in the current directory using the +`ar.dev/v1alpha1` declarative format. No code scaffolding is generated. The generated file can be applied directly: + ```sh arctl apply -f my-prompt.yaml ``` @@ -18,6 +22,7 @@ arctl init prompt NAME [flags] ``` Examples: + ```sh arctl init prompt my-prompt arctl init prompt my-prompt --description "System prompt for summarization" @@ -33,6 +38,12 @@ arctl init prompt my-prompt --description "System prompt for summarization" ## Global flags ```sh --h, --help Display help information for the command. - --output-dir string Parent directory under which the project is created (defaults to the current directory) +-h, --help Display help information for the command. + --output-dir string Parent directory under which the project is created. Defaults to the current directory. + --registry-token string Registry bearer token (defaults to value of ARCTL_API_TOKEN env var) + --registry-url string Registry URL (overrides ARCTL_API_BASE_URL env var; defaults to http://localhost:12121) ``` + +## See also + +* [arctl init](../arctl-init/) - Scaffold a new declarative resource project (agent, MCP server, skill, or prompt) diff --git a/content/docs/reference/cli/arctl-init-skill.md b/content/docs/reference/cli/arctl-init-skill.md index 8a2d4aa..7aabdb4 100644 --- a/content/docs/reference/cli/arctl-init-skill.md +++ b/content/docs/reference/cli/arctl-init-skill.md @@ -1,12 +1,16 @@ --- title: arctl init skill -description: "Scaffold a new skill project with declarative YAML and source stubs." weight: 10 +description: "Scaffold a new skill project with declarative YAML and source stubs." --- -Scaffold a new skill project. Creates a project directory containing a declarative `skill.yaml` (`ar.dev/v1alpha1`) and source stubs. + + +Scaffold a new skill project. Creates a project directory +containing a declarative `skill.yaml` (`ar.dev/v1alpha1`) and source stubs. The generated `skill.yaml` can be applied directly: + ```sh arctl apply -f NAME/skill.yaml ``` @@ -18,6 +22,7 @@ arctl init skill NAME [flags] ``` Examples: + ```sh arctl init skill my-skill arctl init skill my-skill --description "Text summarizer" @@ -32,6 +37,12 @@ arctl init skill my-skill --description "Text summarizer" ## Global flags ```sh --h, --help Display help information for the command. - --output-dir string Parent directory under which the project is created (defaults to the current directory) +-h, --help Display help information for the command. + --output-dir string Parent directory under which the project is created. Defaults to the current directory. + --registry-token string Registry bearer token (defaults to value of ARCTL_API_TOKEN env var) + --registry-url string Registry URL (overrides ARCTL_API_BASE_URL env var; defaults to http://localhost:12121) ``` + +## See also + +* [arctl init](../arctl-init/) - Scaffold a new declarative resource project (agent, MCP server, skill, or prompt) diff --git a/content/docs/reference/cli/arctl-init.md b/content/docs/reference/cli/arctl-init.md index df79af7..38cc33a 100644 --- a/content/docs/reference/cli/arctl-init.md +++ b/content/docs/reference/cli/arctl-init.md @@ -1,26 +1,31 @@ --- title: arctl init -description: "Scaffold a new declarative resource project (agent, MCP server, skill, or prompt)." weight: 10 +description: "Scaffold a new declarative resource project (agent, MCP server, skill, or prompt)." --- -Scaffold a new project. The generated YAML uses the `ar.dev/v1alpha1` declarative format and can be applied directly with `arctl apply`. + + +Scaffold a new project. The generated YAML uses the `ar.dev/v1alpha1` +declarative format and can be applied directly with `arctl apply`. Supported types: -- `agent NAME` — framework + language picker -- `mcp NAME` — framework + language picker -- `skill NAME` -- `prompt NAME` -Run `arctl init` with no arguments for an interactive picker that selects the resource kind. +```sh +agent NAME # picker selects framework + language +mcp NAME # picker selects framework + language +skill NAME +prompt NAME +``` ## Usage ```sh -arctl init TYPE NAME [flags] +arctl init TYPE ... [flags] ``` Examples: + ```sh arctl init agent myagent arctl init agent myagent --framework adk --language python @@ -28,24 +33,27 @@ arctl init mcp my-server arctl init mcp my-server --framework fastmcp --language python arctl init skill my-skill arctl init prompt my-prompt -arctl init # interactive: picker for kind +arctl init # interactive: picker for kind ``` ## Command-specific flags ```sh - --output-dir string Parent directory under which the project is created (defaults to the current directory) + --output-dir string Parent directory under which the project is created. Defaults to the current directory. ``` ## Global flags ```sh --h, --help Display help information for the command. +-h, --help Display help information for the command. + --registry-token string Registry bearer token (defaults to value of ARCTL_API_TOKEN env var) + --registry-url string Registry URL (overrides ARCTL_API_BASE_URL env var; defaults to http://localhost:12121) ``` -## Sub-commands +## See also -- [arctl init agent](arctl-init-agent) — scaffold a new agent project -- [arctl init mcp](arctl-init-mcp) — scaffold a new MCP server project -- [arctl init prompt](arctl-init-prompt) — create a new declarative prompt YAML -- [arctl init skill](arctl-init-skill) — scaffold a new skill project +* [arctl](../arctl/) - Agent Registry CLI +* [arctl init agent](../arctl-init-agent/) - Scaffold a new agent project with declarative YAML and framework stubs +* [arctl init mcp](../arctl-init-mcp/) - Scaffold a new MCP server project with declarative YAML and framework stubs +* [arctl init prompt](../arctl-init-prompt/) - Create a new declarative prompt YAML using the ar.dev/v1alpha1 format +* [arctl init skill](../arctl-init-skill/) - Scaffold a new skill project with declarative YAML and source stubs diff --git a/content/docs/reference/cli/arctl-pull.md b/content/docs/reference/cli/arctl-pull.md index 69060be..8509a7a 100644 --- a/content/docs/reference/cli/arctl-pull.md +++ b/content/docs/reference/cli/arctl-pull.md @@ -1,14 +1,16 @@ --- title: arctl pull -description: "Fetch a registry resource's source repository to a local directory." weight: 10 +description: "Fetch a registry resource's source repository to a local directory." --- -Fetch a registry resource's source repository to a local directory. + -Reads the resource's `spec.source.repository.url` from the registry and clones it into `DIRECTORY` (defaults to `NAME` if omitted). +Fetch a registry resource's source repository to a local directory. -Supported types: `agent`, `mcp`, `skill` +Supported types: `agent`, `mcp`, `skill`. Reads the resource's +`Spec.Source.Repository.URL` from the registry and clones it into `DIRECTORY` +(defaults to `NAME` if omitted). ## Usage @@ -17,6 +19,7 @@ arctl pull TYPE NAME [DIRECTORY] [flags] ``` Examples: + ```sh arctl pull agent myagent arctl pull mcp myserver ./vendor/myserver @@ -36,3 +39,7 @@ arctl pull skill myskill --tag stable --registry-token string Registry bearer token (defaults to value of ARCTL_API_TOKEN env var) --registry-url string Registry URL (overrides ARCTL_API_BASE_URL env var; defaults to http://localhost:12121) ``` + +## See also + +* [arctl](../arctl/) - Agent Registry CLI diff --git a/content/docs/reference/cli/arctl-run.md b/content/docs/reference/cli/arctl-run.md index 4ab70d9..23290e4 100644 --- a/content/docs/reference/cli/arctl-run.md +++ b/content/docs/reference/cli/arctl-run.md @@ -1,16 +1,27 @@ --- title: arctl run -description: "Run the agent or MCP server defined in the current project directory." weight: 10 +description: "Run the agent or MCP server defined in the current project directory." --- -Run the agent or MCP server defined by the declarative YAML in the project directory (defaults to `.`). + + +Run the agent or MCP server defined by the declarative YAML in the +project directory (defaults to "."). -Reads `arctl.yaml` to look up the matching framework by `(framework, language)` and dispatches to its run command. Loads `.env` (if present) and validates that the framework's required env vars are set. +For Agents the default is to start the runtime in the background, wait +until the agent's HTTP endpoint is reachable, then launch an interactive +A2A chat. When chat exits the runtime is torn down. Use `--no-chat` to +keep the old foreground-only behavior. -**For Agent projects:** starts the runtime in the background, waits until the agent's HTTP endpoint is reachable, then launches an interactive A2A chat. When the chat exits, the runtime is torn down. Use `--no-chat` to run in the foreground without chat. +For MCPServer kinds chat does not apply; the framework's run command runs +in the foreground until interrupted. Pass `--inspector` to launch the MCP +Inspector subprocess (requires `npx` on PATH) alongside the server; the +Inspector retries until the server is reachable. -**For MCP server projects:** chat does not apply; the framework's run command runs in the foreground until interrupted. Pass `--inspector` to launch the MCP Inspector alongside the server. +Reads `arctl.yaml` to look up the matching framework by (framework, language) +and dispatches to its run command. Loads `.env` (if present) and validates +that the framework's required env vars are set. ## Usage @@ -19,6 +30,7 @@ arctl run [DIRECTORY] [flags] ``` Examples: + ```sh arctl run arctl run ./myagent @@ -32,13 +44,10 @@ arctl run mymcp --inspector # MCP with MCP Inspector launched ```sh --dry-run Skip actual exec; useful for tests --e, --env strings KEY=VALUE env override (repeatable) - --inspector Launch MCP Inspector alongside the server; it connects when ready - (MCP projects only; errors on agent projects) - --no-chat Skip chat for Agents; run the framework command in the foreground - (agent projects only; errors on MCP projects) - --watch Rebuild and restart on file change (skips chat for agents; - for chat open a second terminal) +-e, --env stringArray KEY=VALUE env override + --inspector Launch MCP Inspector alongside the server; it connects when ready (MCP projects only; errors on agent projects) + --no-chat Skip chat for Agents; run the framework command in the foreground (agent projects only; errors on MCP projects) + --watch Rebuild and restart on file change (skips chat for agents; for chat open a second terminal) ``` ## Global flags @@ -48,3 +57,7 @@ arctl run mymcp --inspector # MCP with MCP Inspector launched --registry-token string Registry bearer token (defaults to value of ARCTL_API_TOKEN env var) --registry-url string Registry URL (overrides ARCTL_API_BASE_URL env var; defaults to http://localhost:12121) ``` + +## See also + +* [arctl](../arctl/) - Agent Registry CLI diff --git a/content/docs/reference/cli/arctl-version.md b/content/docs/reference/cli/arctl-version.md index 48d2ccb..490d0e0 100644 --- a/content/docs/reference/cli/arctl-version.md +++ b/content/docs/reference/cli/arctl-version.md @@ -1,10 +1,12 @@ --- title: arctl version -description: "Display the version of the arctl CLI." weight: 10 +description: "Display the version of the arctl CLI." --- -Displays the version of `arctl`. + + +Displays the version of arctl. ## Usage @@ -12,12 +14,6 @@ Displays the version of `arctl`. arctl version [flags] ``` -Examples: -```sh -arctl version -arctl version --json -``` - ## Command-specific flags ```sh @@ -31,3 +27,7 @@ arctl version --json --registry-token string Registry bearer token (defaults to value of ARCTL_API_TOKEN env var) --registry-url string Registry URL (overrides ARCTL_API_BASE_URL env var; defaults to http://localhost:12121) ``` + +## See also + +* [arctl](../arctl/) - Agent Registry CLI diff --git a/content/docs/reference/cli/arctl-wait.md b/content/docs/reference/cli/arctl-wait.md index c29d0fb..727680d 100644 --- a/content/docs/reference/cli/arctl-wait.md +++ b/content/docs/reference/cli/arctl-wait.md @@ -1,21 +1,28 @@ --- title: arctl wait -description: "Wait for a registry resource to reach a target state." weight: 10 +description: "Wait for a registry resource to reach a target state." --- + + Wait for a registry resource to reach a target state. -Only `deployment` resources are currently supported. +Only deployments are supported. Exit codes: -**Exit codes:** -- `0` — the deployment reached the requested state -- `1` — the deployment reached a different terminal state, doesn't exist, or the timeout was exceeded +```sh +0 the deployment reached the requested state +1 the deployment reached a different terminal state, doesn't exist, or + the timeout was exceeded +``` -**Timeout regimes:** -- `--timeout=5m` (default) — wait up to 5 minutes -- `--timeout=0` — poll once and return the current state -- `--timeout=-1` — wait forever +Timeout regimes: + +```sh +--timeout=5m (default) wait up to 5 minutes +--timeout=0 poll once and return the current state +--timeout=-1 wait forever +``` ## Usage @@ -24,6 +31,7 @@ arctl wait TYPE NAME [flags] ``` Examples: + ```sh arctl wait deployment aws-v1 arctl wait deployment team-a/aws-v1 @@ -45,3 +53,7 @@ arctl wait deployment aws-v1 --for=delete --timeout=10m --registry-token string Registry bearer token (defaults to value of ARCTL_API_TOKEN env var) --registry-url string Registry URL (overrides ARCTL_API_BASE_URL env var; defaults to http://localhost:12121) ``` + +## See also + +* [arctl](../arctl/) - Agent Registry CLI diff --git a/content/docs/reference/cli/arctl.md b/content/docs/reference/cli/arctl.md new file mode 100644 index 0000000..cb754dd --- /dev/null +++ b/content/docs/reference/cli/arctl.md @@ -0,0 +1,33 @@ +--- +title: arctl +weight: 10 +description: "Agent Registry CLI." +--- + + + +arctl is a CLI tool for managing agents, MCP servers, skills, and prompts. + +## Global flags + +```sh +-h, --help Display help information for the command. + --registry-token string Registry bearer token (defaults to value of ARCTL_API_TOKEN env var) + --registry-url string Registry URL (overrides ARCTL_API_BASE_URL env var; defaults to http://localhost:12121) +-v, --version version for arctl +``` + +## See also + +* [arctl apply](../arctl-apply/) - Apply one or more registry resources from a YAML file +* [arctl build](../arctl-build/) - Build a Docker image for a declarative resource project +* [arctl completion](../arctl-completion/) - Generate the autocompletion script for the specified shell +* [arctl configure](../arctl-configure/) - Create the JSON configuration a client needs to connect to arctl +* [arctl db](../arctl-db/) - Database operations for the agent registry (migrations, inspection) +* [arctl delete](../arctl-delete/) - Delete a registry resource by type and name, or from a YAML file +* [arctl get](../arctl-get/) - List or retrieve registry resources by type +* [arctl init](../arctl-init/) - Scaffold a new declarative resource project (agent, MCP server, skill, or prompt) +* [arctl pull](../arctl-pull/) - Fetch a registry resource's source repository to a local directory +* [arctl run](../arctl-run/) - Run the agent or MCP server defined in the current project directory +* [arctl version](../arctl-version/) - Display the version of the arctl CLI +* [arctl wait](../arctl-wait/) - Wait for a registry resource to reach a target state diff --git a/go.mod b/go.mod index 38df11f..7788d20 100644 --- a/go.mod +++ b/go.mod @@ -5,4 +5,4 @@ go 1.25.1 // docs-theme-extras declares the hextra import itself (pinned to v0.12.3), so // hextra is a transitive dependency and is not listed here — matching // agentgateway / kgateway / ambientmesh. Its checksums stay in go.sum. -require github.com/solo-io/docs-theme-extras v0.3.2 // indirect +require github.com/solo-io/docs-theme-extras v0.3.5 // indirect diff --git a/go.sum b/go.sum index 375c933..bd60b62 100644 --- a/go.sum +++ b/go.sum @@ -1,8 +1,2 @@ -github.com/solo-io/docs-theme-extras v0.2.0 h1:GShYCtM7oUC3UqHOqCPwPzsKe9jKdA1OXC0LVqo+h7w= -github.com/solo-io/docs-theme-extras v0.2.0/go.mod h1:jjjYu/QoD+vMu30zgcpfEuTEGuJOJWs5qai/K18kltg= -github.com/solo-io/docs-theme-extras v0.2.2-beta.5 h1:jVUDhC3rbfVbePzc45oFEp1JyuHfiViC+stAFCQTZME= -github.com/solo-io/docs-theme-extras v0.2.2-beta.5/go.mod h1:jjjYu/QoD+vMu30zgcpfEuTEGuJOJWs5qai/K18kltg= -github.com/solo-io/docs-theme-extras v0.2.2-beta.6 h1:eUBymiCl4Q2EnQJEgMINXul2haSQwhKzj1WUr6rCxXU= -github.com/solo-io/docs-theme-extras v0.2.2-beta.6/go.mod h1:jjjYu/QoD+vMu30zgcpfEuTEGuJOJWs5qai/K18kltg= -github.com/solo-io/docs-theme-extras v0.3.2 h1:BmUUvQjgIdB2yvjKW4GnyDKcr/gzchn3oVp3BpOIOw0= -github.com/solo-io/docs-theme-extras v0.3.2/go.mod h1:jjjYu/QoD+vMu30zgcpfEuTEGuJOJWs5qai/K18kltg= +github.com/solo-io/docs-theme-extras v0.3.5 h1:KaCM1CaqV3IyyIY/7uc0z5WHutL0aHA4brV1zGwfGw0= +github.com/solo-io/docs-theme-extras v0.3.5/go.mod h1:jjjYu/QoD+vMu30zgcpfEuTEGuJOJWs5qai/K18kltg= diff --git a/hugo_stats.json b/hugo_stats.json index 5408a94..8cc6dcb 100644 --- a/hugo_stats.json +++ b/hugo_stats.json @@ -4,7 +4,6 @@ "a", "article", "aside", - "blockquote", "body", "br", "button", @@ -155,7 +154,6 @@ "hextra-code-copy-btn", "hextra-code-copy-btn-container", "hextra-copy-icon", - "hextra-error-h1", "hextra-hamburger-menu", "hextra-max-content-width", "hextra-max-navbar-width", @@ -458,6 +456,7 @@ "nav-link-kbd", "nav-links", "page-description", + "pnf-code", "preview-appbar", "preview-appbar-brand", "preview-appbar-right", @@ -498,8 +497,10 @@ "sidebar-toggle", "socials", "solo-breadcrumb", + "solo-breadcrumb-back", "solo-breadcrumb-home", "solo-breadcrumb-link", + "solo-breadcrumb-lone", "solo-breadcrumb-sep", "solo-footer", "solo-footer-inner", @@ -538,19 +539,14 @@ "about-skills", "about-the-registry-catalog", "access-the-ui", - "add-a-prompt-to-an-agent", - "add-a-skill", "add-a-tool", - "add-an-mcp-server", "add-an-mcp-server-to-the-agent", - "add-mcp-server", "agents", "ar-orbit", "arctl-cli", "artifact-registry-infrastructure", "artifacts", "backToTop", - "bash", "bb-panel", "bb-panel-desc", "bb-panel-link", @@ -572,12 +568,6 @@ "create-a-skill", "create-an-agent", "create-an-mcp-server", - "db-migrate-down", - "db-migrate-force", - "db-migrate-goto", - "db-migrate-status", - "db-migrate-up", - "db-migrate-version", "deploy", "deploy-the-mcp-server", "deployed-view", @@ -589,8 +579,6 @@ "faqs", "favicon-svg", "features", - "fish", - "from-the-registry", "gateway", "get-started", "global-flags", @@ -607,8 +595,12 @@ "next", "next-steps", "plugins", + "pnf-home", + "pnf-lede", + "pnf-status", + "pnf-suggestion-list", + "pnf-suggestions", "postgresql", - "powershell", "preview-appbar", "prompts", "public-disclosure", @@ -624,10 +616,10 @@ "remediation", "reports", "rest-api", - "run-the-agent", "run-the-agent-locally", "run-the-mcp-server", "runtimes", + "see-also", "servers", "skills", "skills-and-prompt-version-drift", @@ -636,7 +628,6 @@ "step-1-install-kagent", "step-2-configure-agentregistry", "step-2-verify-the-runtime", - "sub-commands", "supported-clients", "supported-tools", "tabs-panel-tabs-00-0", @@ -645,16 +636,12 @@ "tabs-panel-tabs-01-1", "tabs-panel-tabs-02-0", "tabs-panel-tabs-02-1", - "tabs-panel-tabs-03-0", - "tabs-panel-tabs-03-1", "tabs-tab-tabs-00-0", "tabs-tab-tabs-00-1", "tabs-tab-tabs-01-0", "tabs-tab-tabs-01-1", "tabs-tab-tabs-02-0", "tabs-tab-tabs-02-1", - "tabs-tab-tabs-03-0", - "tabs-tab-tabs-03-1", "terminal", "terminal-body", "test-the-deployed-server", @@ -663,8 +650,7 @@ "updates-and-questions", "usage", "verify-the-agent", - "verify-the-deployment", - "zsh" + "verify-the-deployment" ] } } diff --git a/scripts/generate-arctl-ref.py b/scripts/generate-arctl-ref.py new file mode 100644 index 0000000..da6f28d --- /dev/null +++ b/scripts/generate-arctl-ref.py @@ -0,0 +1,605 @@ +#!/usr/bin/env python3 +""" +Generate the arctl CLI reference for the agentregistry website. + +Writes a throwaway Go program that imports arctl's exported command tree and +runs cobra's doc generator over it, then rewrites the result into finished Hugo +pages under content/docs/reference/cli/ — front matter and body in one file, +matching how the reference was laid out before it was automated. + +The generator program lives here rather than in the product repo so that +publishing docs needs no upstream change, and so cobra/doc's markdown +dependencies stay out of agentregistry's go.mod. It reaches the CLI through a +`replace` directive against a plain checkout; pkg/cli.Root is a documented +public entry point (see that package's README), which is what makes this safe +to depend on from outside the module. + +Every page in content/docs/reference/cli/ is generated. Editing one by hand is +pointless: the next run overwrites it. Change the cobra command definitions in +agentregistry-dev/agentregistry instead. + +Usage (from the workflow, or locally): + AGENTREGISTRY_DIR=/path/to/agentregistry \\ + WEBSITE_DIR=/path/to/website \\ + python3 scripts/generate-arctl-ref.py +""" + +import os +import re +import subprocess +import tempfile +from pathlib import Path + +# The doc generator, written into a temp module at run time. +# +# Three things here are guards, not boilerplate: +# +# docsEnv Several persistent flags seed their *default* from the +# environment — --registry-url defaults to $ARCTL_API_BASE_URL. +# Under the real OSEnv, whatever is exported on the machine +# running generation gets baked into the published flag table, +# so a runner with a staging registry set would silently commit +# that host into the docs. +# +# Version version.Version comes from ldflags and varies per build (a tag +# in CI, "dev" locally). Cobra prints it on the root page, so +# leaving it alone churns the docs for a reason that has nothing +# to do with the CLI's surface. +# +# InitDefault- Cobra adds the `completion` command and the root's --version +# *Cmd/Flag flag lazily inside execute(), so a plain doc run silently omits +# both: four shell subcommands and a flag users can actually pass. +GO_DOC_GEN = '''package main + +import ( +\t"fmt" +\t"log" +\t"os" + +\t"github.com/spf13/cobra/doc" + +\t"github.com/agentregistry-dev/agentregistry/pkg/cli" +\tcliruntime "github.com/agentregistry-dev/agentregistry/pkg/cli/runtime" +) + +type docsEnv struct{} + +var _ cliruntime.Env = docsEnv{} + +func (docsEnv) Getenv(string) string { return "" } + +func main() { +\tif len(os.Args) < 2 { +\t\tfmt.Fprintln(os.Stderr, "usage: gen-arctl-docs ") +\t\tos.Exit(1) +\t} + +\tcfg := cli.DefaultConfig() +\tcfg.Env = docsEnv{} +\tcfg.Version = "latest" + +\troot := cli.Root(cfg) +\troot.InitDefaultCompletionCmd() +\troot.InitDefaultVersionFlag() +\troot.DisableAutoGenTag = true + +\tif err := os.MkdirAll(os.Args[1], 0o755); err != nil { +\t\tlog.Fatalf("creating output directory: %v", err) +\t} +\tif err := doc.GenMarkdownTree(root, os.Args[1]); err != nil { +\t\tlog.Fatalf("generating CLI docs: %v", err) +\t} +} +''' + +# The generator's own module. `go mod tidy` fills in the rest; only the two +# direct requires and the replace matter here. The Go directive is deliberately +# older than agentregistry's own so this keeps working if that repo moves ahead +# of the runner's toolchain. +GO_MOD_TEMPLATE = '''module gen-arctl-docs + +go 1.25 + +require ( +\tgithub.com/agentregistry-dev/agentregistry v0.0.0-00010101000000-000000000000 +\tgithub.com/spf13/cobra v1.10.2 +) + +replace github.com/agentregistry-dev/agentregistry => {agentregistry_path} +''' + +# Path relative to the website checkout. +CONTENT_SUBDIR = Path("content") / "docs" / "reference" / "cli" + +# Every command page shares one weight. Hextra falls back to sorting equal +# weights by title, and every title starts with "arctl", so the root page +# (shortest title) sorts first and the subcommands alphabetize after it. +PAGE_WEIGHT = 10 + +# Warns anyone who opens a page in an editor rather than the site. +GENERATED_NOTICE = ( + "" +) + + +def slug_for(filename: str) -> str: + """arctl_db_migrate_up.md -> arctl-db-migrate-up""" + return Path(filename).stem.replace("_", "-") + + +def title_for(filename: str) -> str: + """arctl_db_migrate_up.md -> arctl db migrate up""" + return Path(filename).stem.replace("_", " ") + + +def yaml_quote(value: str) -> str: + """Quote a scalar for YAML front matter.""" + return '"' + value.replace("\\", "\\\\").replace('"', '\\"') + '"' + + +# The canonical help line. Cobra emits a per-command "help for delete", which +# says nothing a reader does not already know and differs on every page; the +# reference has always carried one shared wording under Global flags instead. +HELP_FLAG = ("-h", "--help", "Display help information for the command.") + +# Prose-only code-span recovery. +# +# The cobra Long strings are Go RAW string literals, and a raw literal is +# delimited by backticks — so a code span cannot be written into one without +# converting every Long to concatenated interpreted strings. That conversion was +# tried and reverted: cobra prints these strings verbatim to the terminal, so +# every backtick added for the docs shows up as literal punctuation in +# `arctl --help`. Terminal readers should not pay for Markdown. +# +# So the formatting is reconstructed here instead. Each pattern is deliberately +# narrow, because a greedy rule silently rewords generated prose that nobody +# reviews. Anything ambiguous is left plain. +CODE_SPAN_PATTERNS = [ + # Long flags: --dry-run, --all-tags. Bounded so "well--formed" is untouched. + re.compile(r"(?.yaml" — the char before that dot is ">", + # so the filename rule above cannot take it first. + re.compile(r"(?])(\.(?:env|gitignore|dockerignore))(?![\w`.])"), + # snake_case identifiers: schema_migrations, pg_advisory_lock. + re.compile(r"(? str: + """Backtick the leading comma-separated identifier run, leaving any tail.""" + m = ENUM_ITEMS.match(items) + if not m: + return items + listed = re.sub(r"(? str: + """Code-span the members of a "Supported types:" style enumeration.""" + lines = prose.split("\n") + for i, line in enumerate(lines): + m = ENUM_LINE.match(line) + if not m: + continue + lines[i] = m.group(1) + m.group(2) + backtick_list(m.group(3)) + if i + 1 < len(lines): + eg = ENUM_EG.match(lines[i + 1]) + if eg: + lines[i + 1] = eg.group(1) + backtick_list(eg.group(2)) + eg.group(3) + return "\n".join(lines) + + +def placeholders_from_usage(usage: str) -> list[str]: + """Collect ALL-CAPS argument placeholders from a command's usage line. + + Deriving them from the usage string rather than a hand-kept list means a + command that renames or adds an argument gets it code-spanned in prose + automatically — and a caps word that is NOT an argument of this command is + never touched. + """ + return sorted({t for t in re.findall(r"\b[A-Z][A-Z0-9]{0,11}\b", usage)}, key=len, reverse=True) + + +def strip_heading(text: str) -> tuple[str, str]: + """Drop cobra's leading `## ` and return (short, rest). + + The heading goes because the front-matter title already renders as the page + H1. The line under it is the command's Short. + """ + without = re.sub(r"^## .+?\n+", "", text, count=1) + short = "" + stripped = without.lstrip() + if stripped and not stripped.startswith(("#", "```")): + short = stripped.split("\n", 1)[0].strip() + without = stripped[len(short):] + return short, without + + +def take_fence(text: str) -> tuple[str, str]: + """Pull the first fenced block out of `text`; return (contents, remainder).""" + m = re.search(r"```[a-z]*\n(.*?)```", text, re.S) + if not m: + return "", text + return m.group(1).strip("\n"), (text[: m.start()] + text[m.end():]) + + +def split_inline_examples(prose: str) -> tuple[str, str]: + """Separate a trailing `Examples:` block from the Long text. + + Several commands embed their examples in the Long rather than cobra's + Example field, as a literal "Examples:" line followed by indented commands. + Left in place those lines are only two spaces deep, which is not enough for + a Markdown code block, so they get swallowed into the preceding paragraph. + Pulled out here they become a real fenced block instead. + """ + m = re.search(r"^Examples?:\s*\n((?:[ \t]+\S.*\n?|[ \t]*\n(?=[ \t]+\S))*)", prose, re.M) + if not m: + return prose, "" + return prose[: m.start()].rstrip(), dedent_block(m.group(1).rstrip()) + + +def dedent_block(block: str) -> str: + """Remove the common leading indent from every line of a block. + + Cobra indents flag tables by two columns and example blocks by two spaces. + The reference has always rendered them flush left inside the fence. + """ + lines = [ln for ln in block.split("\n")] + widths = [len(ln) - len(ln.lstrip()) for ln in lines if ln.strip()] + if not widths: + return block + cut = min(widths) + return "\n".join(ln[cut:] if ln.strip() else "" for ln in lines) + + +def parse_flags(block: str) -> list[tuple[str, str, str]]: + """Split a cobra flag table into (shorthand, name, description) triples. + + A flag line is a spec and a description separated by two or more spaces, + where the spec may or may not lead with a single-letter shorthand: + + -f, --filename string YAML file to read resources from + --all-tags Delete every tag of NAME + + The three parts are kept separate rather than as one spec string because + the shorthand occupies its own column. Splitting it out is what lets + render_flags re-align a table after -h has been moved between sections, + which otherwise collapses the indent that keeps `--all-tags` under the + `--filename` of the line above. + + Anything not matching that shape is passed through as a name with no + description, so an unexpected line survives instead of being dropped. + """ + triples: list[tuple[str, str, str]] = [] + for line in block.split("\n"): + if not line.strip(): + continue + m = re.match(r"^\s*(.*?\S)\s{2,}(\S.*)$", line) + spec, desc = (m.group(1), m.group(2)) if m else (line.strip(), "") + sm = re.match(r"^(-[A-Za-z]), (--.*)$", spec) + triples.append((sm.group(1), sm.group(2), desc) if sm else ("", spec, desc)) + return triples + + +def render_flags(triples: list[tuple[str, str, str]]) -> str: + """Re-align a flag table: shorthand column, then names, then descriptions.""" + if not triples: + return "" + width = max(len(name) for _, name, _ in triples) + lines = [] + for short, name, desc in triples: + prefix = f"{short}, " if short else " " + body = f"{name.ljust(width)} {desc}" if desc else name + lines.append((prefix + body).rstrip()) + return "\n".join(lines) + + +def fence_indented_runs(prose: str) -> str: + """Turn runs of indented lines in the Long into fenced sh blocks. + + Cobra Long strings indent example invocations by two spaces. Two spaces is + not enough to make a Markdown code block, so those lines are absorbed as + lazy continuations of the paragraph above them and render as prose — e.g. + "...sends DELETE /v0/apply. arctl delete -f agent.yaml" run together on one + line. Fencing each run keeps them readable and, because add_code_spans + skips fenced content, also stops the flags inside them being backticked. + """ + out: list[str] = [] + run: list[str] = [] + + def flush() -> None: + # A run of "- item" / "1. item" lines is a Markdown list that a two-space + # indent renders correctly on its own. Fencing it would turn a bulleted + # list of generated files into a shell snippet. + if run and all(re.match(r"\s*([-*+]|\d+\.)\s", ln) for ln in run): + out.extend(ln.strip() for ln in run) + run.clear() + return + if run: + # Blank line first: a fence glued to the paragraph above it renders, + # but reads as a continuation in the source and in Copy-as-Markdown. + if out and out[-1].strip(): + out.append("") + out.append("```sh\n" + dedent_block("\n".join(run)) + "\n```") + run.clear() + + for line in prose.split("\n"): + if line.startswith((" ", "\t")) and line.strip(): + run.append(line) + elif not line.strip() and run: + # A blank line inside an indented run keeps the run open only if + # the next line is indented too; simplest correct call is to close. + flush() + out.append("") + else: + flush() + out.append(line) + flush() + return "\n".join(out) + + +def add_code_spans(prose: str, placeholders: list[str] | None = None) -> str: + """Wrap high-confidence tokens in backticks, skipping fenced/inline code.""" + parts = re.split(r"(```.*?```|`[^`]*`)", prose, flags=re.S) + for i, part in enumerate(parts): + if part.startswith("`"): + continue + part = mark_enumerations(part) + part = SINGLE_QUOTED.sub(lambda m: f"`{m.group(1)}`", part) + for pattern in CODE_SPAN_PATTERNS: + part = pattern.sub(lambda m: f"`{m.group(1)}`", part) + for token in placeholders or []: + part = re.sub(rf"(? str: + """Turn headings inside a Long into bold labels. + + Cobra's own built-in completion help ships `#### Linux:` / `#### macOS:` in + its Long text. Those are sub-labels of a sentence, not page sections, but + Hextra puts every heading in the right-rail TOC — so each of the four + completion pages listed "Linux:" and "macOS:" ABOVE its own "Usage" entry. + They are also a heading-level skip, since nothing above them is an H2 or H3. + + Bold keeps them visible and correctly subordinate without inventing TOC + entries. Applied to prose only, so the section headings this script emits + are unaffected. + """ + return re.sub(r"^#{1,6}\s*(.+?)\s*$", r"**\1**", prose, flags=re.M) + + +def escape_angle_tokens(text: str) -> str: + """Entity-escape ``-style placeholders outside code spans and fences. + + Goldmark runs with `unsafe: true` on this site, so a bare in prose is + parsed as an HTML tag and disappears from the rendered page. The same token + in a front-matter description is worse: extras' page-description partial + pipes the value through `markdownify | plainify`, which renders the token as + a tag and then strips it, so `arctl init prompt`'s description published as + "Create a new declarative .yaml for a prompt." — silently missing the word + it was describing. + + Escaping to entities round-trips correctly: `plainify` leaves them alone and + the partial's closing `htmlUnescape` restores the literal angle brackets. + """ + parts = re.split(r"(```.*?```|`[^`]*`)", text, flags=re.S) + for i, part in enumerate(parts): + if part.startswith("`"): + continue + parts[i] = re.sub( + r"<([a-zA-Z][A-Za-z0-9_-]*)>", r"<\1>", part + ) + return "".join(parts) + + +def rewrite_links(text: str) -> str: + """Point cobra's relative .md cross-links at the published page URLs. + + Cobra emits [arctl db migrate](arctl_db_migrate.md). The pages are siblings + under /docs/reference/cli/, so ..// resolves correctly from any of + them. + + The character class has to allow hyphens: a command whose own name contains + one produces a mixed filename like arctl_configure_claude-code.md, and a + [A-Za-z0-9_]-only pattern silently leaves those links pointing at a .md file + that the site never publishes. + """ + + def sub(match: re.Match) -> str: + return f"[{match.group(1)}](../{slug_for(match.group(2))}/)" + + return re.sub(r"\[([^\]]+)\]\(([A-Za-z0-9_-]+\.md)\)", sub, text) + + +def build_page(raw: str) -> tuple[str, str]: + """Turn one cobra file into (description, body) in the reference's own shape. + + Cobra's layout is man-page shaped: Short, Synopsis, a bare usage fence, + Options, Options inherited from parent commands, SEE ALSO. The reference + reads as a task doc instead — prose, Usage, Command-specific flags, Global + flags — so the sections are re-emitted rather than just renamed. Nothing is + dropped; SEE ALSO is the only section that keeps its position. + """ + short, rest = strip_heading(raw) + + # Cobra writes each section as `### `; split on those. + chunks = re.split(r"^### (.+)$", rest, flags=re.M) + lead, sections = chunks[0], dict(zip(chunks[1::2], chunks[2::2])) + + # The usage fence sits at the end of Synopsis, or in the lead when the + # command sets no Long. + synopsis = sections.get("Synopsis", "") + usage, synopsis = take_fence(synopsis) + if not usage: + usage, lead = take_fence(lead) + + prose, inline_examples = split_inline_examples(synopsis.strip() or "") + examples, _ = take_fence(sections.get("Examples", "")) + examples = dedent_block(examples) if examples else inline_examples + + # Fall back to the Short when the command sets no Long, so a bare parent + # command still says what it is. + body_prose = escape_angle_tokens(add_code_spans( + demote_prose_headings(fence_indented_runs(prose.strip() or short)), + placeholders_from_usage(usage), + )) + + # Both flag tables arrive wrapped in their own fence; parse the contents, + # not the fence markers. + own_flags, _ = take_fence(sections.get("Options", "")) + inherited_flags, _ = take_fence(sections.get("Options inherited from parent commands", "")) + + flags = [t for t in parse_flags(own_flags) if t[1] != "--help"] + inherited = parse_flags(inherited_flags) + + # The root command has no parent, so cobra files its persistent flags + # (--registry-url, --registry-token) under Options rather than under + # "inherited". Those are precisely the flags every subcommand shows as + # global, so listing them as command-specific on the root page contradicts + # all 31 other pages. Absence of an inherited section identifies the root. + if not inherited: + flags, inherited = [], flags + + out = [body_prose] + if usage: + out.append(f"## Usage\n\n```sh\n{usage}\n```") + if examples: + out.append(f"Examples:\n\n```sh\n{examples}\n```") + elif examples: + out.append(f"## Usage\n\n```sh\n{examples}\n```") + if flags: + out.append(f"## Command-specific flags\n\n```sh\n{render_flags(flags)}\n```") + # -h is on every command, so it belongs with the other always-present flags. + out.append( + "## Global flags\n\n```sh\n" + + render_flags([HELP_FLAG] + inherited) + + "\n```" + ) + if "SEE ALSO" in sections: + out.append("## See also\n\n" + rewrite_links(sections["SEE ALSO"]).strip()) + + description = escape_angle_tokens(short.rstrip()) + if description and description[-1] not in ".!?": + description += "." + + return description, "\n\n".join(s.strip() for s in out if s.strip()) + "\n" + + +def clear_stale(directory: Path, keep: set[str]) -> None: + """Delete arctl-*.md pages the current run did not produce. + + Without this, renaming or removing a command leaves its page published + forever. _index.md is hand-maintained and never touched. + """ + for existing in sorted(directory.glob("arctl*.md")): + if existing.name not in keep: + existing.unlink() + print(f" - Removed stale {existing.name}") + + +def run_generator(agentregistry_dir: Path, gen_dir: Path, out_dir: Path) -> None: + """Build and run the doc generator against a plain agentregistry checkout.""" + module_root = agentregistry_dir + if not (module_root / "go.mod").exists(): + raise SystemExit( + f"Error: no go.mod under {module_root}. " + "AGENTREGISTRY_DIR must point at an agentregistry checkout." + ) + + gen_dir.mkdir(parents=True, exist_ok=True) + (gen_dir / "main.go").write_text(GO_DOC_GEN, encoding="utf-8") + (gen_dir / "go.mod").write_text( + GO_MOD_TEMPLATE.format(agentregistry_path=module_root.resolve()), + encoding="utf-8", + ) + + # Resolve cobra/doc and its markdown dependencies into the generator's own + # go.sum. This is the whole reason the program lives in a temp module: those + # deps never touch agentregistry's go.mod. + subprocess.run(["go", "mod", "tidy"], check=True, cwd=gen_dir) + subprocess.run(["go", "run", ".", str(out_dir)], check=True, cwd=gen_dir) + + +def generate(website_dir: Path, agentregistry_dir: Path) -> None: + content_dir = website_dir / CONTENT_SUBDIR + content_dir.mkdir(parents=True, exist_ok=True) + + with tempfile.TemporaryDirectory() as tmp: + raw_dir = Path(tmp) / "raw" + run_generator(agentregistry_dir, Path(tmp) / "gen", raw_dir) + + produced: set[str] = set() + for src in sorted(raw_dir.glob("*.md")): + slug = slug_for(src.name) + title = title_for(src.name) + description, body = build_page(src.read_text(encoding="utf-8")) + description = description or f"Reference for the {title} command." + (content_dir / f"{slug}.md").write_text( + "---\n" + f"title: {title}\n" + f"weight: {PAGE_WEIGHT}\n" + f"description: {yaml_quote(description)}\n" + "---\n\n" + f"{GENERATED_NOTICE}\n\n" + f"{body.strip()}\n", + encoding="utf-8", + ) + produced.add(f"{slug}.md") + print(f" + {slug}") + + clear_stale(content_dir, produced) + + print(f" Generated {len(produced)} arctl command pages.") + + +def main() -> None: + website_dir = Path(os.environ.get("WEBSITE_DIR", ".")).resolve() + agentregistry_dir = Path(os.environ.get("AGENTREGISTRY_DIR", "agentregistry")).resolve() + + if not agentregistry_dir.is_dir(): + raise SystemExit(f"Error: agentregistry checkout not found at {agentregistry_dir}") + if not (website_dir / "hugo.yaml").exists(): + raise SystemExit(f"Error: {website_dir} does not look like the website repo (no hugo.yaml)") + + generate(website_dir, agentregistry_dir) + + +if __name__ == "__main__": + main() From 032939dd6f429a46f3ad5061f52409d1135e8fc6 Mon Sep 17 00:00:00 2001 From: Kristin Brown Date: Fri, 28 Aug 2026 12:49:25 -0400 Subject: [PATCH 2/3] Made descriptions not duplicate and added hextra links Signed-off-by: Kristin Brown --- content/docs/reference/cli/arctl-apply.md | 2 +- content/docs/reference/cli/arctl-build.md | 2 +- .../reference/cli/arctl-completion-bash.md | 2 +- .../reference/cli/arctl-completion-fish.md | 2 +- .../cli/arctl-completion-powershell.md | 4 +- .../reference/cli/arctl-completion-zsh.md | 2 +- .../docs/reference/cli/arctl-completion.md | 10 ++-- .../cli/arctl-configure-claude-code.md | 13 ++++- .../reference/cli/arctl-configure-cursor.md | 13 ++++- .../reference/cli/arctl-configure-kiro.md | 13 ++++- .../reference/cli/arctl-configure-vscode.md | 13 ++++- content/docs/reference/cli/arctl-configure.md | 12 ++--- .../reference/cli/arctl-db-migrate-down.md | 5 +- .../reference/cli/arctl-db-migrate-force.md | 2 +- .../reference/cli/arctl-db-migrate-goto.md | 2 +- .../reference/cli/arctl-db-migrate-status.md | 8 ++- .../docs/reference/cli/arctl-db-migrate-up.md | 2 +- .../reference/cli/arctl-db-migrate-version.md | 2 +- .../docs/reference/cli/arctl-db-migrate.md | 14 ++--- content/docs/reference/cli/arctl-db.md | 11 ++-- content/docs/reference/cli/arctl-delete.md | 6 +-- content/docs/reference/cli/arctl-get.md | 4 +- .../docs/reference/cli/arctl-init-agent.md | 6 +-- content/docs/reference/cli/arctl-init-mcp.md | 6 +-- .../docs/reference/cli/arctl-init-prompt.md | 4 +- .../docs/reference/cli/arctl-init-skill.md | 9 ++-- content/docs/reference/cli/arctl-init.md | 16 +++--- content/docs/reference/cli/arctl-pull.md | 4 +- content/docs/reference/cli/arctl-run.md | 4 +- content/docs/reference/cli/arctl-version.md | 7 +-- content/docs/reference/cli/arctl-wait.md | 5 +- content/docs/reference/cli/arctl.md | 24 ++++----- scripts/generate-arctl-ref.py | 52 +++++++++++++++++-- 33 files changed, 185 insertions(+), 96 deletions(-) diff --git a/content/docs/reference/cli/arctl-apply.md b/content/docs/reference/cli/arctl-apply.md index cf6873e..9e3e0d7 100644 --- a/content/docs/reference/cli/arctl-apply.md +++ b/content/docs/reference/cli/arctl-apply.md @@ -43,4 +43,4 @@ cat stack.yaml | arctl apply -f - ## See also -* [arctl](../arctl/) - Agent Registry CLI +* [arctl]({{< link-hextra path="/reference/cli/arctl/" >}}) - Agent Registry CLI diff --git a/content/docs/reference/cli/arctl-build.md b/content/docs/reference/cli/arctl-build.md index 899ad03..2917a2c 100644 --- a/content/docs/reference/cli/arctl-build.md +++ b/content/docs/reference/cli/arctl-build.md @@ -46,4 +46,4 @@ arctl build ./my-agent --image ghcr.io/acme/my-agent:v1.0.0 --platform linux/am ## See also -* [arctl](../arctl/) - Agent Registry CLI +* [arctl]({{< link-hextra path="/reference/cli/arctl/" >}}) - Agent Registry CLI diff --git a/content/docs/reference/cli/arctl-completion-bash.md b/content/docs/reference/cli/arctl-completion-bash.md index aa20c8d..88c8937 100644 --- a/content/docs/reference/cli/arctl-completion-bash.md +++ b/content/docs/reference/cli/arctl-completion-bash.md @@ -53,4 +53,4 @@ arctl completion bash ## See also -* [arctl completion](../arctl-completion/) - Generate the autocompletion script for the specified shell +* [arctl completion]({{< link-hextra path="/reference/cli/arctl-completion/" >}}) - Generate the autocompletion script for the specified shell diff --git a/content/docs/reference/cli/arctl-completion-fish.md b/content/docs/reference/cli/arctl-completion-fish.md index 4eff580..5440345 100644 --- a/content/docs/reference/cli/arctl-completion-fish.md +++ b/content/docs/reference/cli/arctl-completion-fish.md @@ -44,4 +44,4 @@ arctl completion fish [flags] ## See also -* [arctl completion](../arctl-completion/) - Generate the autocompletion script for the specified shell +* [arctl completion]({{< link-hextra path="/reference/cli/arctl-completion/" >}}) - Generate the autocompletion script for the specified shell diff --git a/content/docs/reference/cli/arctl-completion-powershell.md b/content/docs/reference/cli/arctl-completion-powershell.md index 726b689..0a05b63 100644 --- a/content/docs/reference/cli/arctl-completion-powershell.md +++ b/content/docs/reference/cli/arctl-completion-powershell.md @@ -6,8 +6,6 @@ description: "Generate the autocompletion script for powershell." -Generate the autocompletion script for powershell. - To load completions in your current shell session: ```sh @@ -39,4 +37,4 @@ arctl completion powershell [flags] ## See also -* [arctl completion](../arctl-completion/) - Generate the autocompletion script for the specified shell +* [arctl completion]({{< link-hextra path="/reference/cli/arctl-completion/" >}}) - Generate the autocompletion script for the specified shell diff --git a/content/docs/reference/cli/arctl-completion-zsh.md b/content/docs/reference/cli/arctl-completion-zsh.md index a498191..0240cdb 100644 --- a/content/docs/reference/cli/arctl-completion-zsh.md +++ b/content/docs/reference/cli/arctl-completion-zsh.md @@ -57,4 +57,4 @@ arctl completion zsh [flags] ## See also -* [arctl completion](../arctl-completion/) - Generate the autocompletion script for the specified shell +* [arctl completion]({{< link-hextra path="/reference/cli/arctl-completion/" >}}) - Generate the autocompletion script for the specified shell diff --git a/content/docs/reference/cli/arctl-completion.md b/content/docs/reference/cli/arctl-completion.md index 6263cd9..6190c42 100644 --- a/content/docs/reference/cli/arctl-completion.md +++ b/content/docs/reference/cli/arctl-completion.md @@ -19,8 +19,8 @@ See each sub-command's help for details on how to use the generated script. ## See also -* [arctl](../arctl/) - Agent Registry CLI -* [arctl completion bash](../arctl-completion-bash/) - Generate the autocompletion script for bash -* [arctl completion fish](../arctl-completion-fish/) - Generate the autocompletion script for fish -* [arctl completion powershell](../arctl-completion-powershell/) - Generate the autocompletion script for powershell -* [arctl completion zsh](../arctl-completion-zsh/) - Generate the autocompletion script for zsh +* [arctl]({{< link-hextra path="/reference/cli/arctl/" >}}) - Agent Registry CLI +* [arctl completion bash]({{< link-hextra path="/reference/cli/arctl-completion-bash/" >}}) - Generate the autocompletion script for bash +* [arctl completion fish]({{< link-hextra path="/reference/cli/arctl-completion-fish/" >}}) - Generate the autocompletion script for fish +* [arctl completion powershell]({{< link-hextra path="/reference/cli/arctl-completion-powershell/" >}}) - Generate the autocompletion script for powershell +* [arctl completion zsh]({{< link-hextra path="/reference/cli/arctl-completion-zsh/" >}}) - Generate the autocompletion script for zsh diff --git a/content/docs/reference/cli/arctl-configure-claude-code.md b/content/docs/reference/cli/arctl-configure-claude-code.md index 505d02e..ca72659 100644 --- a/content/docs/reference/cli/arctl-configure-claude-code.md +++ b/content/docs/reference/cli/arctl-configure-claude-code.md @@ -6,7 +6,16 @@ description: "Configure Claude Code." -Configure Claude Code +Write the MCP server entry that Claude Code reads, so it can reach this registry. + +The entry is merged into the client's existing configuration file rather than +replacing it, and the file is created if it does not exist yet. + +The endpoint defaults to http://localhost:21212/mcp. Override the port with `--port`, +or the whole URL with `--url`. Clients that support OAuth authenticate +interactively; for static or direct access, pass `--token-env` with the name of +the environment variable holding the MCP bearer token. Only that name is written +into the config, never the token itself. ## Usage @@ -32,4 +41,4 @@ arctl configure claude-code [flags] ## See also -* [arctl configure](../arctl-configure/) - Create the JSON configuration a client needs to connect to arctl +* [arctl configure]({{< link-hextra path="/reference/cli/arctl-configure/" >}}) - Write the JSON config a client needs to connect to arctl diff --git a/content/docs/reference/cli/arctl-configure-cursor.md b/content/docs/reference/cli/arctl-configure-cursor.md index c713966..942802e 100644 --- a/content/docs/reference/cli/arctl-configure-cursor.md +++ b/content/docs/reference/cli/arctl-configure-cursor.md @@ -6,7 +6,16 @@ description: "Configure Cursor AI Editor." -Configure Cursor AI Editor +Write the MCP server entry that Cursor AI Editor reads, so it can reach this registry. + +The entry is merged into the client's existing configuration file rather than +replacing it, and the file is created if it does not exist yet. + +The endpoint defaults to http://localhost:21212/mcp. Override the port with `--port`, +or the whole URL with `--url`. Clients that support OAuth authenticate +interactively; for static or direct access, pass `--token-env` with the name of +the environment variable holding the MCP bearer token. Only that name is written +into the config, never the token itself. ## Usage @@ -32,4 +41,4 @@ arctl configure cursor [flags] ## See also -* [arctl configure](../arctl-configure/) - Create the JSON configuration a client needs to connect to arctl +* [arctl configure]({{< link-hextra path="/reference/cli/arctl-configure/" >}}) - Write the JSON config a client needs to connect to arctl diff --git a/content/docs/reference/cli/arctl-configure-kiro.md b/content/docs/reference/cli/arctl-configure-kiro.md index 47aa2fc..bf16346 100644 --- a/content/docs/reference/cli/arctl-configure-kiro.md +++ b/content/docs/reference/cli/arctl-configure-kiro.md @@ -6,7 +6,16 @@ description: "Configure Kiro agentic IDE." -Configure Kiro agentic IDE +Write the MCP server entry that Kiro agentic IDE reads, so it can reach this registry. + +The entry is merged into the client's existing configuration file rather than +replacing it, and the file is created if it does not exist yet. + +The endpoint defaults to http://localhost:21212/mcp. Override the port with `--port`, +or the whole URL with `--url`. Clients that support OAuth authenticate +interactively; for static or direct access, pass `--token-env` with the name of +the environment variable holding the MCP bearer token. Only that name is written +into the config, never the token itself. ## Usage @@ -32,4 +41,4 @@ arctl configure kiro [flags] ## See also -* [arctl configure](../arctl-configure/) - Create the JSON configuration a client needs to connect to arctl +* [arctl configure]({{< link-hextra path="/reference/cli/arctl-configure/" >}}) - Write the JSON config a client needs to connect to arctl diff --git a/content/docs/reference/cli/arctl-configure-vscode.md b/content/docs/reference/cli/arctl-configure-vscode.md index 9682464..23cfab7 100644 --- a/content/docs/reference/cli/arctl-configure-vscode.md +++ b/content/docs/reference/cli/arctl-configure-vscode.md @@ -6,7 +6,16 @@ description: "Configure Visual Studio Code." -Configure Visual Studio Code +Write the MCP server entry that Visual Studio Code reads, so it can reach this registry. + +The entry is merged into the client's existing configuration file rather than +replacing it, and the file is created if it does not exist yet. + +The endpoint defaults to http://localhost:21212/mcp. Override the port with `--port`, +or the whole URL with `--url`. Clients that support OAuth authenticate +interactively; for static or direct access, pass `--token-env` with the name of +the environment variable holding the MCP bearer token. Only that name is written +into the config, never the token itself. ## Usage @@ -32,4 +41,4 @@ arctl configure vscode [flags] ## See also -* [arctl configure](../arctl-configure/) - Create the JSON configuration a client needs to connect to arctl +* [arctl configure]({{< link-hextra path="/reference/cli/arctl-configure/" >}}) - Write the JSON config a client needs to connect to arctl diff --git a/content/docs/reference/cli/arctl-configure.md b/content/docs/reference/cli/arctl-configure.md index 478e5e6..712ab6e 100644 --- a/content/docs/reference/cli/arctl-configure.md +++ b/content/docs/reference/cli/arctl-configure.md @@ -1,7 +1,7 @@ --- title: arctl configure weight: 10 -description: "Create the JSON configuration a client needs to connect to arctl." +description: "Write the JSON config a client needs to connect to arctl." --- @@ -18,8 +18,8 @@ Creates the .json configuration for each client, so it can connect to arctl. ## See also -* [arctl](../arctl/) - Agent Registry CLI -* [arctl configure claude-code](../arctl-configure-claude-code/) - Configure Claude Code -* [arctl configure cursor](../arctl-configure-cursor/) - Configure Cursor AI Editor -* [arctl configure kiro](../arctl-configure-kiro/) - Configure Kiro agentic IDE -* [arctl configure vscode](../arctl-configure-vscode/) - Configure Visual Studio Code +* [arctl]({{< link-hextra path="/reference/cli/arctl/" >}}) - Agent Registry CLI +* [arctl configure claude-code]({{< link-hextra path="/reference/cli/arctl-configure-claude-code/" >}}) - Configure Claude Code +* [arctl configure cursor]({{< link-hextra path="/reference/cli/arctl-configure-cursor/" >}}) - Configure Cursor AI Editor +* [arctl configure kiro]({{< link-hextra path="/reference/cli/arctl-configure-kiro/" >}}) - Configure Kiro agentic IDE +* [arctl configure vscode]({{< link-hextra path="/reference/cli/arctl-configure-vscode/" >}}) - Configure Visual Studio Code diff --git a/content/docs/reference/cli/arctl-db-migrate-down.md b/content/docs/reference/cli/arctl-db-migrate-down.md index f82d53a..0684ee0 100644 --- a/content/docs/reference/cli/arctl-db-migrate-down.md +++ b/content/docs/reference/cli/arctl-db-migrate-down.md @@ -6,7 +6,8 @@ description: "Roll back the N most-recent applied migrations for the selected so -Roll back the `N` most-recent applied migrations for the selected source. +Undo the last `N` applied migrations, newest first, by running each +migration's .down.sql. Migrations whose .down.sql raises (up-only / not-reversible migrations) will leave the `schema_migrations` row marked dirty after the failed @@ -31,4 +32,4 @@ arctl db migrate down N [flags] ## See also -* [arctl db migrate](../arctl-db-migrate/) - Apply, roll back, and inspect database migrations +* [arctl db migrate]({{< link-hextra path="/reference/cli/arctl-db-migrate/" >}}) - Apply, roll back, and inspect database migrations diff --git a/content/docs/reference/cli/arctl-db-migrate-force.md b/content/docs/reference/cli/arctl-db-migrate-force.md index ce0f4fc..edc5ad2 100644 --- a/content/docs/reference/cli/arctl-db-migrate-force.md +++ b/content/docs/reference/cli/arctl-db-migrate-force.md @@ -29,4 +29,4 @@ arctl db migrate force V [flags] ## See also -* [arctl db migrate](../arctl-db-migrate/) - Apply, roll back, and inspect database migrations +* [arctl db migrate]({{< link-hextra path="/reference/cli/arctl-db-migrate/" >}}) - Apply, roll back, and inspect database migrations diff --git a/content/docs/reference/cli/arctl-db-migrate-goto.md b/content/docs/reference/cli/arctl-db-migrate-goto.md index 9e14f9b..be1bb8c 100644 --- a/content/docs/reference/cli/arctl-db-migrate-goto.md +++ b/content/docs/reference/cli/arctl-db-migrate-goto.md @@ -27,4 +27,4 @@ arctl db migrate goto V [flags] ## See also -* [arctl db migrate](../arctl-db-migrate/) - Apply, roll back, and inspect database migrations +* [arctl db migrate]({{< link-hextra path="/reference/cli/arctl-db-migrate/" >}}) - Apply, roll back, and inspect database migrations diff --git a/content/docs/reference/cli/arctl-db-migrate-status.md b/content/docs/reference/cli/arctl-db-migrate-status.md index 7a3591e..4a04b2e 100644 --- a/content/docs/reference/cli/arctl-db-migrate-status.md +++ b/content/docs/reference/cli/arctl-db-migrate-status.md @@ -6,7 +6,11 @@ description: "Show how many migrations are applied vs pending across all sources -Show how many migrations are applied vs pending across all sources +Report how many migrations are applied and how many are still pending, +without changing anything. + +Counts are aggregated across every registered source, so `--source` is not +accepted here. Pass `--output` json for a machine-readable summary. ## Usage @@ -31,4 +35,4 @@ arctl db migrate status [flags] ## See also -* [arctl db migrate](../arctl-db-migrate/) - Apply, roll back, and inspect database migrations +* [arctl db migrate]({{< link-hextra path="/reference/cli/arctl-db-migrate/" >}}) - Apply, roll back, and inspect database migrations diff --git a/content/docs/reference/cli/arctl-db-migrate-up.md b/content/docs/reference/cli/arctl-db-migrate-up.md index e629e96..a52db8f 100644 --- a/content/docs/reference/cli/arctl-db-migrate-up.md +++ b/content/docs/reference/cli/arctl-db-migrate-up.md @@ -31,4 +31,4 @@ arctl db migrate up [flags] ## See also -* [arctl db migrate](../arctl-db-migrate/) - Apply, roll back, and inspect database migrations +* [arctl db migrate]({{< link-hextra path="/reference/cli/arctl-db-migrate/" >}}) - Apply, roll back, and inspect database migrations diff --git a/content/docs/reference/cli/arctl-db-migrate-version.md b/content/docs/reference/cli/arctl-db-migrate-version.md index f1fb8ad..58d8c1a 100644 --- a/content/docs/reference/cli/arctl-db-migrate-version.md +++ b/content/docs/reference/cli/arctl-db-migrate-version.md @@ -28,4 +28,4 @@ arctl db migrate version [flags] ## See also -* [arctl db migrate](../arctl-db-migrate/) - Apply, roll back, and inspect database migrations +* [arctl db migrate]({{< link-hextra path="/reference/cli/arctl-db-migrate/" >}}) - Apply, roll back, and inspect database migrations diff --git a/content/docs/reference/cli/arctl-db-migrate.md b/content/docs/reference/cli/arctl-db-migrate.md index d6c39d1..d5cc2f3 100644 --- a/content/docs/reference/cli/arctl-db-migrate.md +++ b/content/docs/reference/cli/arctl-db-migrate.md @@ -26,10 +26,10 @@ of server startup. Reads `AGENT_REGISTRY_DATABASE_URL` from the environment when ## See also -* [arctl db](../arctl-db/) - Database operations for the agent registry (migrations, inspection) -* [arctl db migrate down](../arctl-db-migrate-down/) - Roll back the N most-recent applied migrations for the selected source -* [arctl db migrate force](../arctl-db-migrate-force/) - Mark version V as applied without running its SQL -* [arctl db migrate goto](../arctl-db-migrate-goto/) - Move the selected source's schema to version V -* [arctl db migrate status](../arctl-db-migrate-status/) - Show how many migrations are applied vs pending across all sources -* [arctl db migrate up](../arctl-db-migrate-up/) - Apply all pending migrations across every registered source -* [arctl db migrate version](../arctl-db-migrate-version/) - Print the highest applied migration version +* [arctl db]({{< link-hextra path="/reference/cli/arctl-db/" >}}) - Database operations (migrations, inspection) +* [arctl db migrate down]({{< link-hextra path="/reference/cli/arctl-db-migrate-down/" >}}) - Roll back the N most-recent applied migrations for the selected source +* [arctl db migrate force]({{< link-hextra path="/reference/cli/arctl-db-migrate-force/" >}}) - Mark version V as applied without running its SQL +* [arctl db migrate goto]({{< link-hextra path="/reference/cli/arctl-db-migrate-goto/" >}}) - Move the selected source's schema to version V +* [arctl db migrate status]({{< link-hextra path="/reference/cli/arctl-db-migrate-status/" >}}) - Show how many migrations are applied vs pending across all sources +* [arctl db migrate up]({{< link-hextra path="/reference/cli/arctl-db-migrate-up/" >}}) - Apply all pending migrations across every registered source +* [arctl db migrate version]({{< link-hextra path="/reference/cli/arctl-db-migrate-version/" >}}) - Print the highest applied migration version diff --git a/content/docs/reference/cli/arctl-db.md b/content/docs/reference/cli/arctl-db.md index e2befbd..5ca2fca 100644 --- a/content/docs/reference/cli/arctl-db.md +++ b/content/docs/reference/cli/arctl-db.md @@ -1,12 +1,15 @@ --- title: arctl db weight: 10 -description: "Database operations for the agent registry (migrations, inspection)." +description: "Database operations (migrations, inspection)." --- -Database operations for the agent registry (migrations, inspection) +Work with the agent registry database directly, without starting the server. + +Covers schema migrations: apply pending migrations, roll them back, and inspect +which version each registered migration source is on. ## Global flags @@ -18,5 +21,5 @@ Database operations for the agent registry (migrations, inspection) ## See also -* [arctl](../arctl/) - Agent Registry CLI -* [arctl db migrate](../arctl-db-migrate/) - Apply, roll back, and inspect database migrations +* [arctl]({{< link-hextra path="/reference/cli/arctl/" >}}) - Agent Registry CLI +* [arctl db migrate]({{< link-hextra path="/reference/cli/arctl-db-migrate/" >}}) - Apply, roll back, and inspect database migrations diff --git a/content/docs/reference/cli/arctl-delete.md b/content/docs/reference/cli/arctl-delete.md index 67ec3bf..0b2d835 100644 --- a/content/docs/reference/cli/arctl-delete.md +++ b/content/docs/reference/cli/arctl-delete.md @@ -1,12 +1,12 @@ --- title: arctl delete weight: 10 -description: "Delete a registry resource by type and name, or from a YAML file." +description: "Delete a registry resource by type and name, or from a file." --- -Delete a registry resource. +Delete a registry resource by type and name, or from a YAML file. File mode (declarative): reads resources from the YAML file and sends `DELETE /v0/apply`. @@ -59,4 +59,4 @@ arctl delete deployment team-a/my-agent ## See also -* [arctl](../arctl/) - Agent Registry CLI +* [arctl]({{< link-hextra path="/reference/cli/arctl/" >}}) - Agent Registry CLI diff --git a/content/docs/reference/cli/arctl-get.md b/content/docs/reference/cli/arctl-get.md index 7cfe7d3..4c30153 100644 --- a/content/docs/reference/cli/arctl-get.md +++ b/content/docs/reference/cli/arctl-get.md @@ -6,7 +6,7 @@ description: "List or retrieve registry resources by type." -List or retrieve registry resources by type. +List every resource of a type, or fetch a single one by name. Supported types: `agents`, `mcps`, `skills`, `prompts`, `runtimes`, `deployments` (singular and uppercase forms also accepted, e.g. `Agent`, `agent`, `agents`) @@ -59,4 +59,4 @@ arctl get skills -o json ## See also -* [arctl](../arctl/) - Agent Registry CLI +* [arctl]({{< link-hextra path="/reference/cli/arctl/" >}}) - Agent Registry CLI diff --git a/content/docs/reference/cli/arctl-init-agent.md b/content/docs/reference/cli/arctl-init-agent.md index 9947b57..fee21b1 100644 --- a/content/docs/reference/cli/arctl-init-agent.md +++ b/content/docs/reference/cli/arctl-init-agent.md @@ -1,12 +1,12 @@ --- title: arctl init agent weight: 10 -description: "Scaffold a new agent project with declarative YAML and framework stubs." +description: "Scaffold an agent project with YAML and framework stubs." --- -Scaffold a new agent project. +Scaffold a new agent project with declarative YAML and framework stubs. Picks a framework + language interactively (or via `--framework` / `--language`). Writes: @@ -63,4 +63,4 @@ arctl init agent myagent --local-mcp ../my-mcp ## See also -* [arctl init](../arctl-init/) - Scaffold a new declarative resource project (agent, MCP server, skill, or prompt) +* [arctl init]({{< link-hextra path="/reference/cli/arctl-init/" >}}) - Scaffold a declarative agent, MCP, skill, or prompt project diff --git a/content/docs/reference/cli/arctl-init-mcp.md b/content/docs/reference/cli/arctl-init-mcp.md index 26ea22f..e133c50 100644 --- a/content/docs/reference/cli/arctl-init-mcp.md +++ b/content/docs/reference/cli/arctl-init-mcp.md @@ -1,12 +1,12 @@ --- title: arctl init mcp weight: 10 -description: "Scaffold a new MCP server project with declarative YAML and framework stubs." +description: "Scaffold an MCP server project with YAML and framework stubs." --- -Scaffold a new MCP server project. +Scaffold a new MCP server project with declarative YAML and framework stubs. `NAME` must be DNS-1123 subdomain: lowercase alphanumeric, hyphens, and dots; max 253 chars; each dot-separated segment must start and end with alphanumeric (max 63 chars per segment). @@ -48,4 +48,4 @@ arctl init mcp my-stdio --framework fastmcp --language python --transport stdio ## See also -* [arctl init](../arctl-init/) - Scaffold a new declarative resource project (agent, MCP server, skill, or prompt) +* [arctl init]({{< link-hextra path="/reference/cli/arctl-init/" >}}) - Scaffold a declarative agent, MCP, skill, or prompt project diff --git a/content/docs/reference/cli/arctl-init-prompt.md b/content/docs/reference/cli/arctl-init-prompt.md index 8510656..916a55c 100644 --- a/content/docs/reference/cli/arctl-init-prompt.md +++ b/content/docs/reference/cli/arctl-init-prompt.md @@ -1,7 +1,7 @@ --- title: arctl init prompt weight: 10 -description: "Create a new declarative prompt YAML using the ar.dev/v1alpha1 format." +description: "Create a declarative prompt YAML (ar.dev/v1alpha1)." --- @@ -46,4 +46,4 @@ arctl init prompt my-prompt --description "System prompt for summarization" ## See also -* [arctl init](../arctl-init/) - Scaffold a new declarative resource project (agent, MCP server, skill, or prompt) +* [arctl init]({{< link-hextra path="/reference/cli/arctl-init/" >}}) - Scaffold a declarative agent, MCP, skill, or prompt project diff --git a/content/docs/reference/cli/arctl-init-skill.md b/content/docs/reference/cli/arctl-init-skill.md index 7aabdb4..2f12a9c 100644 --- a/content/docs/reference/cli/arctl-init-skill.md +++ b/content/docs/reference/cli/arctl-init-skill.md @@ -1,13 +1,14 @@ --- title: arctl init skill weight: 10 -description: "Scaffold a new skill project with declarative YAML and source stubs." +description: "Scaffold a skill project with YAML and source stubs." --- -Scaffold a new skill project. Creates a project directory -containing a declarative `skill.yaml` (`ar.dev/v1alpha1`) and source stubs. +Scaffold a new skill project with declarative YAML and source stubs. + +Creates a project directory containing a `skill.yaml` in the `ar.dev/v1alpha1` format. The generated `skill.yaml` can be applied directly: @@ -45,4 +46,4 @@ arctl init skill my-skill --description "Text summarizer" ## See also -* [arctl init](../arctl-init/) - Scaffold a new declarative resource project (agent, MCP server, skill, or prompt) +* [arctl init]({{< link-hextra path="/reference/cli/arctl-init/" >}}) - Scaffold a declarative agent, MCP, skill, or prompt project diff --git a/content/docs/reference/cli/arctl-init.md b/content/docs/reference/cli/arctl-init.md index 38cc33a..aac3ab0 100644 --- a/content/docs/reference/cli/arctl-init.md +++ b/content/docs/reference/cli/arctl-init.md @@ -1,12 +1,14 @@ --- title: arctl init weight: 10 -description: "Scaffold a new declarative resource project (agent, MCP server, skill, or prompt)." +description: "Scaffold a declarative agent, MCP, skill, or prompt project." --- -Scaffold a new project. The generated YAML uses the `ar.dev/v1alpha1` +Scaffold a new declarative resource project: an agent, MCP server, skill, or prompt. + +The generated YAML uses the `ar.dev/v1alpha1` declarative format and can be applied directly with `arctl apply`. Supported types: @@ -52,8 +54,8 @@ arctl init # interactive: picker for kind ## See also -* [arctl](../arctl/) - Agent Registry CLI -* [arctl init agent](../arctl-init-agent/) - Scaffold a new agent project with declarative YAML and framework stubs -* [arctl init mcp](../arctl-init-mcp/) - Scaffold a new MCP server project with declarative YAML and framework stubs -* [arctl init prompt](../arctl-init-prompt/) - Create a new declarative prompt YAML using the ar.dev/v1alpha1 format -* [arctl init skill](../arctl-init-skill/) - Scaffold a new skill project with declarative YAML and source stubs +* [arctl]({{< link-hextra path="/reference/cli/arctl/" >}}) - Agent Registry CLI +* [arctl init agent]({{< link-hextra path="/reference/cli/arctl-init-agent/" >}}) - Scaffold an agent project with YAML and framework stubs +* [arctl init mcp]({{< link-hextra path="/reference/cli/arctl-init-mcp/" >}}) - Scaffold an MCP server project with YAML and framework stubs +* [arctl init prompt]({{< link-hextra path="/reference/cli/arctl-init-prompt/" >}}) - Create a declarative prompt YAML (ar.dev/v1alpha1) +* [arctl init skill]({{< link-hextra path="/reference/cli/arctl-init-skill/" >}}) - Scaffold a skill project with YAML and source stubs diff --git a/content/docs/reference/cli/arctl-pull.md b/content/docs/reference/cli/arctl-pull.md index 8509a7a..dd22c2d 100644 --- a/content/docs/reference/cli/arctl-pull.md +++ b/content/docs/reference/cli/arctl-pull.md @@ -1,7 +1,7 @@ --- title: arctl pull weight: 10 -description: "Fetch a registry resource's source repository to a local directory." +description: "Fetch a registry resource's source repo to a local directory." --- @@ -42,4 +42,4 @@ arctl pull skill myskill --tag stable ## See also -* [arctl](../arctl/) - Agent Registry CLI +* [arctl]({{< link-hextra path="/reference/cli/arctl/" >}}) - Agent Registry CLI diff --git a/content/docs/reference/cli/arctl-run.md b/content/docs/reference/cli/arctl-run.md index 23290e4..5878d25 100644 --- a/content/docs/reference/cli/arctl-run.md +++ b/content/docs/reference/cli/arctl-run.md @@ -1,7 +1,7 @@ --- title: arctl run weight: 10 -description: "Run the agent or MCP server defined in the current project directory." +description: "Run the agent or MCP server in the current project directory." --- @@ -60,4 +60,4 @@ arctl run mymcp --inspector # MCP with MCP Inspector launched ## See also -* [arctl](../arctl/) - Agent Registry CLI +* [arctl]({{< link-hextra path="/reference/cli/arctl/" >}}) - Agent Registry CLI diff --git a/content/docs/reference/cli/arctl-version.md b/content/docs/reference/cli/arctl-version.md index 490d0e0..8e1f606 100644 --- a/content/docs/reference/cli/arctl-version.md +++ b/content/docs/reference/cli/arctl-version.md @@ -1,12 +1,13 @@ --- title: arctl version weight: 10 -description: "Display the version of the arctl CLI." +description: "Display the arctl CLI and registry server versions." --- -Displays the version of arctl. +Displays the version, git commit, and build date of the arctl CLI, and of +the registry server when one is reachable. ## Usage @@ -30,4 +31,4 @@ arctl version [flags] ## See also -* [arctl](../arctl/) - Agent Registry CLI +* [arctl]({{< link-hextra path="/reference/cli/arctl/" >}}) - Agent Registry CLI diff --git a/content/docs/reference/cli/arctl-wait.md b/content/docs/reference/cli/arctl-wait.md index 727680d..3b8530d 100644 --- a/content/docs/reference/cli/arctl-wait.md +++ b/content/docs/reference/cli/arctl-wait.md @@ -6,7 +6,8 @@ description: "Wait for a registry resource to reach a target state." -Wait for a registry resource to reach a target state. +Wait for a registry resource to reach a target state, polling until it +gets there or the timeout expires. Only deployments are supported. Exit codes: @@ -56,4 +57,4 @@ arctl wait deployment aws-v1 --for=delete --timeout=10m ## See also -* [arctl](../arctl/) - Agent Registry CLI +* [arctl]({{< link-hextra path="/reference/cli/arctl/" >}}) - Agent Registry CLI diff --git a/content/docs/reference/cli/arctl.md b/content/docs/reference/cli/arctl.md index cb754dd..dd13914 100644 --- a/content/docs/reference/cli/arctl.md +++ b/content/docs/reference/cli/arctl.md @@ -19,15 +19,15 @@ arctl is a CLI tool for managing agents, MCP servers, skills, and prompts. ## See also -* [arctl apply](../arctl-apply/) - Apply one or more registry resources from a YAML file -* [arctl build](../arctl-build/) - Build a Docker image for a declarative resource project -* [arctl completion](../arctl-completion/) - Generate the autocompletion script for the specified shell -* [arctl configure](../arctl-configure/) - Create the JSON configuration a client needs to connect to arctl -* [arctl db](../arctl-db/) - Database operations for the agent registry (migrations, inspection) -* [arctl delete](../arctl-delete/) - Delete a registry resource by type and name, or from a YAML file -* [arctl get](../arctl-get/) - List or retrieve registry resources by type -* [arctl init](../arctl-init/) - Scaffold a new declarative resource project (agent, MCP server, skill, or prompt) -* [arctl pull](../arctl-pull/) - Fetch a registry resource's source repository to a local directory -* [arctl run](../arctl-run/) - Run the agent or MCP server defined in the current project directory -* [arctl version](../arctl-version/) - Display the version of the arctl CLI -* [arctl wait](../arctl-wait/) - Wait for a registry resource to reach a target state +* [arctl apply]({{< link-hextra path="/reference/cli/arctl-apply/" >}}) - Apply one or more registry resources from a YAML file +* [arctl build]({{< link-hextra path="/reference/cli/arctl-build/" >}}) - Build a Docker image for a declarative resource project +* [arctl completion]({{< link-hextra path="/reference/cli/arctl-completion/" >}}) - Generate the autocompletion script for the specified shell +* [arctl configure]({{< link-hextra path="/reference/cli/arctl-configure/" >}}) - Write the JSON config a client needs to connect to arctl +* [arctl db]({{< link-hextra path="/reference/cli/arctl-db/" >}}) - Database operations (migrations, inspection) +* [arctl delete]({{< link-hextra path="/reference/cli/arctl-delete/" >}}) - Delete a registry resource by type and name, or from a file +* [arctl get]({{< link-hextra path="/reference/cli/arctl-get/" >}}) - List or retrieve registry resources by type +* [arctl init]({{< link-hextra path="/reference/cli/arctl-init/" >}}) - Scaffold a declarative agent, MCP, skill, or prompt project +* [arctl pull]({{< link-hextra path="/reference/cli/arctl-pull/" >}}) - Fetch a registry resource's source repo to a local directory +* [arctl run]({{< link-hextra path="/reference/cli/arctl-run/" >}}) - Run the agent or MCP server in the current project directory +* [arctl version]({{< link-hextra path="/reference/cli/arctl-version/" >}}) - Display the arctl CLI and registry server versions +* [arctl wait]({{< link-hextra path="/reference/cli/arctl-wait/" >}}) - Wait for a registry resource to reach a target state diff --git a/scripts/generate-arctl-ref.py b/scripts/generate-arctl-ref.py index da6f28d..134fb06 100644 --- a/scripts/generate-arctl-ref.py +++ b/scripts/generate-arctl-ref.py @@ -111,6 +111,11 @@ # Path relative to the website checkout. CONTENT_SUBDIR = Path("content") / "docs" / "reference" / "cli" +# The same location expressed as a docs-relative path, for `link-hextra`. That +# shortcode resolves against the docs root (content/docs), so the `content/docs` +# prefix is dropped and a trailing slash is kept to match the published URLs. +DOCS_LINK_PREFIX = "/" + "/".join(CONTENT_SUBDIR.parts[2:]) + "/" + # Every command page shares one weight. Hextra falls back to sorting equal # weights by title, and every title starts with "arctl", so the root page # (shortest title) sorts first and the subcommands alphabetize after it. @@ -430,11 +435,14 @@ def escape_angle_tokens(text: str) -> str: def rewrite_links(text: str) -> str: - """Point cobra's relative .md cross-links at the published page URLs. + """Rewrite cobra's relative .md cross-links as `link-hextra` calls. - Cobra emits [arctl db migrate](arctl_db_migrate.md). The pages are siblings - under /docs/reference/cli/, so ..// resolves correctly from any of - them. + Cobra emits [arctl db migrate](arctl_db_migrate.md). A plain relative URL + would work for this site as it stands, but `link-hextra` is the canonical + resolver: it produces a version- and product-aware URL, and it is what the + `rebase`/`reuse` pipelines feed version and product context into when + content is pulled into another tree. Hard-coded relative links silently + resolve to the wrong tree in that situation; these do not. The character class has to allow hyphens: a command whose own name contains one produces a mixed filename like arctl_configure_claude-code.md, and a @@ -443,11 +451,40 @@ def rewrite_links(text: str) -> str: """ def sub(match: re.Match) -> str: - return f"[{match.group(1)}](../{slug_for(match.group(2))}/)" + slug = slug_for(match.group(2)) + return ( + f"[{match.group(1)}]" + f'({{{{< link-hextra path="{DOCS_LINK_PREFIX}{slug}/" >}}}})' + ) return re.sub(r"\[([^\]]+)\]\(([A-Za-z0-9_-]+\.md)\)", sub, text) +def drop_redundant_opener(prose: str, short: str) -> str: + """Drop the Long's opening paragraph when it only restates the Short. + + The Short becomes the page description, so a Long that opens by repeating it + verbatim prints the same sentence twice — once in , once as the first + thing on the page. Most of those are fixed at the source, but cobra's own + built-in `completion powershell` help does it too, and forking cobra's + strings to fix one cosmetic line is the wrong trade. + + Only fires when there is something after the opening paragraph, so a command + whose entire Long is one restating sentence keeps its body rather than + rendering as a bare heading. + """ + paragraphs = prose.split("\n\n") + if len(paragraphs) < 2: + return prose + + def norm(text: str) -> str: + return re.sub(r"\s+", " ", text).strip().rstrip(".").lower() + + if norm(paragraphs[0]) == norm(short): + return "\n\n".join(paragraphs[1:]).lstrip() + return prose + + def build_page(raw: str) -> tuple[str, str]: """Turn one cobra file into (description, body) in the reference's own shape. @@ -476,6 +513,8 @@ def build_page(raw: str) -> tuple[str, str]: # Fall back to the Short when the command sets no Long, so a bare parent # command still says what it is. + prose = drop_redundant_opener(prose.strip(), short) + body_prose = escape_angle_tokens(add_code_spans( demote_prose_headings(fence_indented_runs(prose.strip() or short)), placeholders_from_usage(usage), @@ -515,6 +554,9 @@ def build_page(raw: str) -> tuple[str, str]: if "SEE ALSO" in sections: out.append("## See also\n\n" + rewrite_links(sections["SEE ALSO"]).strip()) + # Short is the command's one-line summary, which is what a page description + # is. Deriving it from the Long instead just restates the sentence the body + # already opens with, word for word. description = escape_angle_tokens(short.rstrip()) if description and description[-1] not in ".!?": description += "." From a3bd3dc38a11c2395f558d05bcf35c51181fff76 Mon Sep 17 00:00:00 2001 From: Kristin Brown Date: Fri, 28 Aug 2026 13:07:32 -0400 Subject: [PATCH 3/3] Added helm and api retrieval Signed-off-by: Kristin Brown --- .github/workflows/reference-docs.yml | 51 +- assets/ar-docs/openapi.yaml | 3726 ++++++++++++++++++++++++++ content/docs/reference/_index.md | 2 +- content/docs/reference/api.md | 15 + content/docs/reference/helm.md | 126 + hugo_stats.json | 3 + scripts/generate-api-ref.py | 90 + scripts/generate-helm-ref.py | 136 + scripts/helm-values.gotmpl | 1 + 9 files changed, 4132 insertions(+), 18 deletions(-) create mode 100644 assets/ar-docs/openapi.yaml create mode 100644 content/docs/reference/api.md create mode 100644 content/docs/reference/helm.md create mode 100644 scripts/generate-api-ref.py create mode 100644 scripts/generate-helm-ref.py create mode 100644 scripts/helm-values.gotmpl diff --git a/.github/workflows/reference-docs.yml b/.github/workflows/reference-docs.yml index 62f5686..a4b9d0f 100644 --- a/.github/workflows/reference-docs.yml +++ b/.github/workflows/reference-docs.yml @@ -1,11 +1,17 @@ -# Regenerates the arctl CLI reference from the agentregistry product repo and -# opens a PR with the result. +# Regenerates the reference docs from the agentregistry product repo and opens a +# PR with the result. Three sources, one PR: # -# Everything lives on this side: scripts/generate-arctl-ref.py builds a -# throwaway Go module that imports arctl's exported command tree through a -# `replace` directive against a plain checkout, runs cobra's doc generator, and -# rewrites the result into Hugo pages. agentregistry needs no changes to support -# this, and cobra/doc's markdown dependencies stay out of its go.mod. +# arctl CLI generate-arctl-ref.py builds a throwaway Go module that imports +# arctl's exported command tree through a `replace` directive, +# runs cobra's doc generator, and rewrites the output into Hugo +# pages. cobra/doc's markdown dependencies stay out of the +# product's go.mod because they live in that throwaway module. +# Helm values generate-helm-ref.py runs the helm-docs pinned in the product +# repo's tools module, with our own values-only template. +# REST API generate-api-ref.py copies openapi.yaml into assets/ so the +# spec is served same-origin. +# +# agentregistry needs no changes to support any of this. # # agentregistry docs are unversioned — one flat content tree — so unlike the # equivalent agentgateway workflow there is no version matrix here. @@ -41,8 +47,8 @@ permissions: pull-requests: write jobs: - arctl-reference: - name: Generate arctl CLI reference + reference: + name: Generate reference docs runs-on: ubuntu-latest timeout-minutes: 20 steps: @@ -69,11 +75,16 @@ jobs: go-version-file: agentregistry/go.mod cache: false - - name: Generate the arctl reference + # helm-docs is invoked through `go tool -modfile=tools/go.mod`, and + # `make charts-generate` needs envsubst (preinstalled on ubuntu runners). + - name: Generate the reference docs env: WEBSITE_DIR: website AGENTREGISTRY_DIR: agentregistry - run: python3 website/scripts/generate-arctl-ref.py + run: | + python3 website/scripts/generate-arctl-ref.py + python3 website/scripts/generate-helm-ref.py + python3 website/scripts/generate-api-ref.py - name: Open a PR id: pr @@ -83,19 +94,25 @@ jobs: base: main branch: ref-docs-arctl delete-branch: true - title: '[Automated] Update the arctl CLI reference' + title: '[Automated] Update the reference docs' commit-message: | - docs: regenerate the arctl CLI reference from agentregistry ${{ steps.source.outputs.sha }} + docs: regenerate the CLI, Helm, and API reference from agentregistry ${{ steps.source.outputs.sha }} Signed-off-by: GitHub Action committer: GitHub Action body: | - Regenerated the arctl CLI reference from + Regenerated the reference docs from [`${{ steps.source.outputs.sha }}`](https://github.com/agentregistry-dev/agentregistry/commit/${{ steps.source.outputs.sha }}). - Every page under `content/docs/reference/cli/` is generated, front matter - included. Edit the cobra command definitions upstream rather than these - files — the next run overwrites anything changed by hand. + | Page | Generated from | + |---|---| + | `content/docs/reference/cli/` | the arctl cobra command definitions | + | `content/docs/reference/helm.md` | the chart's `values.yaml`, via helm-docs | + | `content/docs/reference/api.md` + `assets/ar-docs/openapi.yaml` | `openapi.yaml` | + + All of these are generated, front matter included. Edit the sources + upstream rather than these files — the next run overwrites anything + changed by hand. Opened automatically by the [Reference docs workflow](https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}). labels: | diff --git a/assets/ar-docs/openapi.yaml b/assets/ar-docs/openapi.yaml new file mode 100644 index 0000000..a7521a5 --- /dev/null +++ b/assets/ar-docs/openapi.yaml @@ -0,0 +1,3726 @@ +components: + schemas: + Agent: + additionalProperties: false + properties: + apiVersion: + type: string + kind: + type: string + metadata: + $ref: '#/components/schemas/ObjectMeta' + spec: + $ref: '#/components/schemas/AgentSpec' + status: + $ref: '#/components/schemas/Status' + required: + - metadata + - spec + - apiVersion + - kind + type: object + AgentSource: + additionalProperties: false + properties: + image: + type: string + protocol: + enum: + - A2A + - HTTP + type: string + repository: + $ref: '#/components/schemas/Repository' + type: object + AgentSpec: + additionalProperties: false + properties: + compatibleHarnesses: + items: + $ref: '#/components/schemas/HarnessCompatibility' + type: + - array + - "null" + description: + type: string + iconUrl: + type: string + instructions: + $ref: '#/components/schemas/ResourceRef' + mcpServers: + items: + $ref: '#/components/schemas/ResourceRef' + type: + - array + - "null" + modelName: + deprecated: true + type: string + modelProvider: + deprecated: true + type: string + plugins: + items: + $ref: '#/components/schemas/ResourceRef' + type: + - array + - "null" + skills: + items: + $ref: '#/components/schemas/ResourceRef' + type: + - array + - "null" + source: + $ref: '#/components/schemas/AgentSource' + title: + type: string + type: object + ApplyResult: + additionalProperties: false + properties: + apiVersion: + type: string + error: + type: string + kind: + type: string + name: + type: string + namespace: + type: string + status: + type: string + tag: + type: string + required: + - name + - status + type: object + ApplyResultsResponse: + additionalProperties: false + properties: + results: + items: + $ref: '#/components/schemas/ApplyResult' + type: + - array + - "null" + required: + - results + type: object + CommandEntry: + additionalProperties: false + properties: + allowedTools: + items: + type: string + type: + - array + - "null" + argumentHint: + type: string + content: + type: string + description: + type: string + model: + type: string + source: + type: string + type: object + CommandsField: + additionalProperties: false + properties: + Map: + additionalProperties: + $ref: '#/components/schemas/CommandEntry' + type: object + Paths: + $ref: '#/components/schemas/PathOrPaths' + required: + - Paths + - Map + type: object + Condition: + additionalProperties: false + properties: + lastTransitionTime: + format: date-time + type: string + message: + type: string + reason: + type: string + status: + type: string + type: + type: string + required: + - type + - status + type: object + Deployment: + additionalProperties: false + properties: + apiVersion: + type: string + kind: + type: string + metadata: + $ref: '#/components/schemas/ObjectMeta' + spec: + $ref: '#/components/schemas/DeploymentSpec' + status: + $ref: '#/components/schemas/Status' + required: + - metadata + - spec + - apiVersion + - kind + type: object + DeploymentHarness: + additionalProperties: false + properties: + permissionMode: + type: string + type: + type: string + required: + - type + type: object + DeploymentRef: + additionalProperties: false + properties: + name: + type: string + namespace: + type: string + required: + - name + type: object + DeploymentSpec: + additionalProperties: false + properties: + deploymentRefs: + items: + $ref: '#/components/schemas/DeploymentRef' + type: + - array + - "null" + desiredState: + type: string + env: + additionalProperties: + type: string + type: object + harness: + $ref: '#/components/schemas/DeploymentHarness' + modelRef: + $ref: '#/components/schemas/ModelRef' + runtimeConfig: + additionalProperties: {} + type: object + runtimeRef: + $ref: '#/components/schemas/ResourceRef' + targetRef: + $ref: '#/components/schemas/ResourceRef' + required: + - targetRef + - runtimeRef + type: object + ErrorDetail: + additionalProperties: false + properties: + location: + description: Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id' + type: string + message: + description: Error message text + type: string + value: + description: The value at the given location + type: object + ErrorModel: + additionalProperties: false + properties: + detail: + description: A human-readable explanation specific to this occurrence of + the problem. + examples: + - Property foo is required but is missing. + type: string + errors: + description: Optional list of individual error details + items: + $ref: '#/components/schemas/ErrorDetail' + type: + - array + - "null" + instance: + description: A URI reference that identifies the specific occurrence of + the problem. + examples: + - https://example.com/error-log/abc123 + format: uri + type: string + status: + description: HTTP status code + examples: + - 400 + format: int64 + type: integer + title: + description: A short, human-readable summary of the problem type. This value + should not change between occurrences of the error. + examples: + - Bad Request + type: string + type: + default: about:blank + description: A URI reference to human-readable documentation for the error. + examples: + - https://example.com/errors/example + format: uri + type: string + type: object + HTTPHeader: + additionalProperties: false + properties: + name: + type: string + value: + type: string + required: + - name + type: object + HarnessCompatibility: + additionalProperties: false + properties: + type: + type: string + required: + - type + type: object + HealthBody: + additionalProperties: false + properties: + status: + description: Health status + examples: + - ok + type: string + required: + - status + type: object + HookEntry: + additionalProperties: false + properties: + allowedEnvVars: + items: + type: string + type: + - array + - "null" + async: + type: boolean + asyncRewake: + type: boolean + command: + type: string + headers: + additionalProperties: + type: string + type: object + if: + type: string + input: {} + model: + type: string + once: + type: boolean + prompt: + type: string + server: + type: string + shell: + type: string + statusMessage: + type: string + timeout: + format: double + type: number + tool: + type: string + type: + type: string + url: + type: string + required: + - type + type: object + HookMatcherGroup: + additionalProperties: false + properties: + hooks: + items: + $ref: '#/components/schemas/HookEntry' + type: + - array + - "null" + matcher: + type: string + required: + - hooks + type: object + HooksField: + additionalProperties: false + properties: + Events: + additionalProperties: + items: + $ref: '#/components/schemas/HookMatcherGroup' + type: + - array + - "null" + type: object + Path: + type: string + Raw: {} + required: + - Path + - Events + - Raw + type: object + LSPServerEntry: + additionalProperties: false + properties: + args: + items: + type: string + type: + - array + - "null" + command: + type: string + env: + additionalProperties: + type: string + type: object + extensionToLanguage: + additionalProperties: + type: string + type: object + initializationOptions: {} + maxRestarts: + format: int64 + type: integer + settings: {} + startupTimeout: + format: int64 + type: integer + transport: + type: string + workspaceFolder: + type: string + required: + - command + - extensionToLanguage + type: object + LSPServersField: + additionalProperties: false + properties: + Path: + type: string + Raw: {} + Servers: + additionalProperties: + $ref: '#/components/schemas/LSPServerEntry' + type: object + required: + - Path + - Servers + - Raw + type: object + ListMetadata: + additionalProperties: false + properties: + count: + format: int64 + type: integer + nextCursor: + type: string + required: + - count + type: object + ListOutputAgentBody: + additionalProperties: false + properties: + items: + items: + $ref: '#/components/schemas/Agent' + type: + - array + - "null" + nextCursor: + type: string + required: + - items + type: object + ListOutputDeploymentBody: + additionalProperties: false + properties: + items: + items: + $ref: '#/components/schemas/Deployment' + type: + - array + - "null" + nextCursor: + type: string + required: + - items + type: object + ListOutputMCPServerBody: + additionalProperties: false + properties: + items: + items: + $ref: '#/components/schemas/MCPServer' + type: + - array + - "null" + nextCursor: + type: string + required: + - items + type: object + ListOutputModelBody: + additionalProperties: false + properties: + items: + items: + $ref: '#/components/schemas/Model' + type: + - array + - "null" + nextCursor: + type: string + required: + - items + type: object + ListOutputPluginBody: + additionalProperties: false + properties: + items: + items: + $ref: '#/components/schemas/Plugin' + type: + - array + - "null" + nextCursor: + type: string + required: + - items + type: object + ListOutputPromptBody: + additionalProperties: false + properties: + items: + items: + $ref: '#/components/schemas/Prompt' + type: + - array + - "null" + nextCursor: + type: string + required: + - items + type: object + ListOutputRuntimeBody: + additionalProperties: false + properties: + items: + items: + $ref: '#/components/schemas/Runtime' + type: + - array + - "null" + nextCursor: + type: string + required: + - items + type: object + ListOutputSecretBody: + additionalProperties: false + properties: + items: + items: + $ref: '#/components/schemas/Secret' + type: + - array + - "null" + nextCursor: + type: string + required: + - items + type: object + ListOutputSkillBody: + additionalProperties: false + properties: + items: + items: + $ref: '#/components/schemas/Skill' + type: + - array + - "null" + nextCursor: + type: string + required: + - items + type: object + LocalSecretReference: + additionalProperties: false + properties: + name: + type: string + required: + - name + type: object + MCPArgument: + additionalProperties: false + properties: + name: + type: string + type: + type: string + value: + type: string + required: + - type + type: object + MCPKeyValueInput: + additionalProperties: false + properties: + isRequired: + type: boolean + name: + type: string + value: + type: string + required: + - name + type: object + MCPPackage: + additionalProperties: false + properties: + launch: + $ref: '#/components/schemas/MCPPackageLaunch' + origin: + $ref: '#/components/schemas/MCPPackageOrigin' + transport: + $ref: '#/components/schemas/MCPTransport' + required: + - origin + - transport + type: object + MCPPackageLaunch: + additionalProperties: false + properties: + args: + items: + $ref: '#/components/schemas/MCPArgument' + type: + - array + - "null" + command: + type: string + env: + items: + $ref: '#/components/schemas/MCPKeyValueInput' + type: + - array + - "null" + type: object + MCPPackageOrigin: + additionalProperties: false + properties: + identifier: + type: string + npm: + $ref: '#/components/schemas/MCPPackageOriginNPM' + oci: + $ref: '#/components/schemas/MCPPackageOriginOCI' + pypi: + $ref: '#/components/schemas/MCPPackageOriginPyPI' + type: + type: string + required: + - type + - identifier + type: object + MCPPackageOriginNPM: + additionalProperties: false + properties: + mirror: + type: string + serverName: + type: string + version: + type: string + required: + - version + - serverName + type: object + MCPPackageOriginOCI: + additionalProperties: false + properties: + serverName: + type: string + required: + - serverName + type: object + MCPPackageOriginPyPI: + additionalProperties: false + properties: + mirror: + type: string + serverName: + type: string + version: + type: string + required: + - version + - serverName + type: object + MCPRemote: + additionalProperties: false + properties: + headers: + items: + $ref: '#/components/schemas/HTTPHeader' + type: + - array + - "null" + type: + type: string + url: + type: string + required: + - type + - url + type: object + MCPServer: + additionalProperties: false + properties: + apiVersion: + type: string + kind: + type: string + metadata: + $ref: '#/components/schemas/ObjectMeta' + spec: + $ref: '#/components/schemas/MCPServerSpec' + status: + $ref: '#/components/schemas/Status' + required: + - metadata + - spec + - apiVersion + - kind + type: object + MCPServerEntry: + additionalProperties: false + properties: + args: + items: + type: string + type: + - array + - "null" + command: + type: string + env: + additionalProperties: + type: string + type: object + headers: + additionalProperties: + type: string + type: object + headersHelper: + type: string + oauth: + $ref: '#/components/schemas/MCPServerOAuth' + type: + type: string + url: + type: string + type: object + MCPServerOAuth: + additionalProperties: false + properties: + authServerMetadataUrl: + type: string + callbackPort: + format: int64 + type: integer + clientId: + type: string + scopes: + items: + type: string + type: + - array + - "null" + type: object + MCPServerSource: + additionalProperties: false + properties: + package: + $ref: '#/components/schemas/MCPPackage' + repository: + $ref: '#/components/schemas/Repository' + type: object + MCPServerSpec: + additionalProperties: false + properties: + description: + type: string + iconUrl: + type: string + remote: + $ref: '#/components/schemas/MCPRemote' + source: + $ref: '#/components/schemas/MCPServerSource' + title: + type: string + type: object + MCPServersField: + additionalProperties: false + properties: + Path: + type: string + Raw: {} + Servers: + additionalProperties: + $ref: '#/components/schemas/MCPServerEntry' + type: object + required: + - Path + - Servers + - Raw + type: object + MCPTransport: + additionalProperties: false + properties: + path: + type: string + port: + format: int32 + minimum: 0 + type: integer + type: + type: string + required: + - type + type: object + MarketplaceResponse: + additionalProperties: false + properties: + $schema: + type: string + name: + type: string + owner: + $ref: '#/components/schemas/Owner' + plugins: + items: + $ref: '#/components/schemas/PluginEntry' + type: array + required: + - name + - owner + - plugins + type: object + Model: + additionalProperties: false + properties: + apiVersion: + type: string + kind: + type: string + metadata: + $ref: '#/components/schemas/ObjectMeta' + spec: + $ref: '#/components/schemas/ModelSpec' + status: + $ref: '#/components/schemas/Status' + required: + - metadata + - spec + - apiVersion + - kind + type: object + ModelAuthConfig: + additionalProperties: false + properties: + secretRef: + $ref: '#/components/schemas/SecretKeyRef' + strategy: + enum: + - runtime + - secretRef + - passthrough + type: string + required: + - strategy + type: object + ModelEndpointConfig: + additionalProperties: false + properties: + baseUrl: + type: string + region: + type: string + tls: + $ref: '#/components/schemas/ModelTLSConfig' + type: object + ModelRef: + additionalProperties: false + properties: + name: + type: string + namespace: + type: string + tag: + type: string + required: + - name + type: object + ModelSpec: + additionalProperties: false + properties: + auth: + $ref: '#/components/schemas/ModelAuthConfig' + description: + type: string + endpoint: + $ref: '#/components/schemas/ModelEndpointConfig' + iconUrl: + type: string + model: + type: string + provider: + enum: + - bedrock + type: string + title: + type: string + required: + - provider + - model + type: object + ModelTLSConfig: + additionalProperties: false + properties: + caCertSecretRef: + $ref: '#/components/schemas/SecretKeyRef' + disableVerify: + type: boolean + type: object + MonitorEntry: + additionalProperties: false + properties: + command: + type: string + description: + type: string + name: + type: string + when: + type: string + required: + - name + - command + - description + type: object + MonitorsField: + additionalProperties: false + properties: + Entries: + items: + $ref: '#/components/schemas/MonitorEntry' + type: + - array + - "null" + Path: + type: string + required: + - Path + - Entries + type: object + ObjectMeta: + additionalProperties: false + properties: + annotations: + additionalProperties: + type: string + type: object + createdAt: + format: date-time + type: string + deletionTimestamp: + format: date-time + type: string + labels: + additionalProperties: + type: string + type: object + name: + type: string + namespace: + type: string + tag: + type: string + uid: + type: string + updatedAt: + format: date-time + type: string + required: + - name + type: object + OfficialMeta: + additionalProperties: false + properties: + isLatest: + type: boolean + publishedAt: + type: string + status: + type: string + statusChangedAt: + type: string + updatedAt: + type: string + required: + - isLatest + type: object + Owner: + additionalProperties: false + properties: + email: + type: string + name: + type: string + required: + - name + type: object + PathOrPaths: + additionalProperties: false + properties: + Values: + items: + type: string + type: + - array + - "null" + WasArray: + type: boolean + required: + - Values + - WasArray + type: object + PingBody: + additionalProperties: false + properties: + pong: + description: Ping response + examples: + - true + type: boolean + required: + - pong + type: object + Plugin: + additionalProperties: false + properties: + apiVersion: + type: string + kind: + type: string + metadata: + $ref: '#/components/schemas/ObjectMeta' + spec: + $ref: '#/components/schemas/PluginSpec' + status: + $ref: '#/components/schemas/PluginStatus' + required: + - metadata + - spec + - apiVersion + - kind + type: object + PluginAuthor: + additionalProperties: false + properties: + email: + type: string + name: + type: string + url: + type: string + required: + - name + type: object + PluginChannel: + additionalProperties: false + properties: + displayName: + type: string + server: + type: string + userConfig: + additionalProperties: + $ref: '#/components/schemas/PluginUserConfigField' + type: object + required: + - server + type: object + PluginDependency: + additionalProperties: false + properties: + marketplace: + type: string + name: + type: string + version: + type: string + type: object + PluginEntry: + additionalProperties: false + properties: + description: + type: string + name: + type: string + source: {} + version: + type: string + required: + - name + - source + type: object + PluginExperimental: + additionalProperties: false + properties: + monitors: + $ref: '#/components/schemas/MonitorsField' + themes: + $ref: '#/components/schemas/PathOrPaths' + type: object + PluginHook: + additionalProperties: false + properties: + event: + type: string + type: + type: string + required: + - event + type: object + PluginInventory: + additionalProperties: false + properties: + agents: + items: + type: string + type: + - array + - "null" + commands: + items: + type: string + type: + - array + - "null" + executables: + items: + type: string + type: + - array + - "null" + hooks: + items: + $ref: '#/components/schemas/PluginHook' + type: + - array + - "null" + mcpServers: + items: + type: string + type: + - array + - "null" + skills: + items: + $ref: '#/components/schemas/PluginSkill' + type: + - array + - "null" + type: object + PluginManifest: + additionalProperties: false + properties: + $schema: + type: string + agents: + $ref: '#/components/schemas/PathOrPaths' + author: + $ref: '#/components/schemas/PluginAuthor' + channels: + items: + $ref: '#/components/schemas/PluginChannel' + type: + - array + - "null" + commands: + $ref: '#/components/schemas/CommandsField' + defaultEnabled: + type: boolean + dependencies: + items: + $ref: '#/components/schemas/PluginDependency' + type: + - array + - "null" + description: + type: string + displayName: + type: string + experimental: + $ref: '#/components/schemas/PluginExperimental' + homepage: + type: string + hooks: + $ref: '#/components/schemas/HooksField' + keywords: + items: + type: string + type: + - array + - "null" + license: + type: string + lspServers: + $ref: '#/components/schemas/LSPServersField' + mcpServers: + $ref: '#/components/schemas/MCPServersField' + monitors: + $ref: '#/components/schemas/MonitorsField' + name: + type: string + outputStyles: + $ref: '#/components/schemas/PathOrPaths' + repository: + type: string + settings: {} + skills: + $ref: '#/components/schemas/PathOrPaths' + themes: + $ref: '#/components/schemas/PathOrPaths' + userConfig: + additionalProperties: + $ref: '#/components/schemas/PluginUserConfigField' + type: object + version: + type: string + required: + - name + type: object + PluginResolvedSource: + additionalProperties: false + properties: + commit: + type: string + digest: + type: string + type: + type: string + required: + - type + type: object + PluginSkill: + additionalProperties: false + properties: + description: + type: string + name: + type: string + required: + - name + type: object + PluginSource: + additionalProperties: false + properties: + git: + $ref: '#/components/schemas/PluginSourceGit' + oci: + $ref: '#/components/schemas/PluginSourceOCI' + type: + type: string + required: + - type + type: object + PluginSourceGit: + additionalProperties: false + properties: + repository: + $ref: '#/components/schemas/Repository' + required: + - repository + type: object + PluginSourceOCI: + additionalProperties: false + properties: + reference: + type: string + required: + - reference + type: object + PluginSpec: + additionalProperties: false + properties: + description: + type: string + harnesses: + items: + type: string + type: + - array + - "null" + iconUrl: + type: string + source: + $ref: '#/components/schemas/PluginSource' + title: + type: string + type: object + PluginStatus: + additionalProperties: false + properties: + conditions: + items: + $ref: '#/components/schemas/Condition' + type: + - array + - "null" + details: {} + inventory: + $ref: '#/components/schemas/PluginInventory' + manifest: + $ref: '#/components/schemas/PluginManifest' + resolvedSource: + $ref: '#/components/schemas/PluginResolvedSource' + type: object + PluginUserConfigField: + additionalProperties: false + properties: + default: {} + description: + type: string + max: + format: double + type: number + min: + format: double + type: number + multiple: + type: boolean + required: + type: boolean + sensitive: + type: boolean + title: + type: string + type: + type: string + required: + - type + - title + - description + type: object + Prompt: + additionalProperties: false + properties: + apiVersion: + type: string + kind: + type: string + metadata: + $ref: '#/components/schemas/ObjectMeta' + spec: + $ref: '#/components/schemas/PromptSpec' + status: + $ref: '#/components/schemas/Status' + required: + - metadata + - spec + - apiVersion + - kind + type: object + PromptSpec: + additionalProperties: false + properties: + content: + type: string + description: + type: string + iconUrl: + type: string + type: object + Repository: + additionalProperties: false + properties: + branch: + type: string + commit: + type: string + credentialsRef: + $ref: '#/components/schemas/LocalSecretReference' + subfolder: + type: string + url: + type: string + type: object + ResourceRef: + additionalProperties: false + properties: + kind: + type: string + name: + type: string + namespace: + type: string + tag: + type: string + required: + - kind + - name + type: object + ResponseMeta: + additionalProperties: false + properties: + io.modelcontextprotocol.registry/official: + $ref: '#/components/schemas/OfficialMeta' + type: object + Runtime: + additionalProperties: false + properties: + apiVersion: + type: string + kind: + type: string + metadata: + $ref: '#/components/schemas/ObjectMeta' + spec: + $ref: '#/components/schemas/RuntimeSpec' + status: + $ref: '#/components/schemas/Status' + required: + - metadata + - spec + - apiVersion + - kind + type: object + RuntimeSpec: + additionalProperties: false + properties: + config: + additionalProperties: {} + type: object + telemetryEndpoint: + type: string + type: + type: string + required: + - type + type: object + Secret: + additionalProperties: false + properties: + apiVersion: + type: string + kind: + type: string + metadata: + $ref: '#/components/schemas/ObjectMeta' + spec: + $ref: '#/components/schemas/SecretSpec' + status: + $ref: '#/components/schemas/SecretStatus' + required: + - metadata + - spec + - apiVersion + - kind + type: object + SecretKeyRef: + additionalProperties: false + properties: + key: + type: string + name: + type: string + namespace: + type: string + required: + - name + type: object + SecretSpec: + additionalProperties: false + properties: + data: + additionalProperties: + type: string + type: object + immutable: + type: boolean + stringData: + additionalProperties: + type: string + type: object + type: + type: string + type: object + SecretStatus: + additionalProperties: false + properties: + dataKeys: + items: + type: string + type: + - array + - "null" + type: object + ServerArgument: + additionalProperties: false + properties: + name: + type: string + type: + type: string + value: + type: string + required: + - type + type: object + ServerDetail: + additionalProperties: false + properties: + $schema: + type: string + description: + type: string + name: + type: string + packages: + items: + $ref: '#/components/schemas/ServerPackage' + type: + - array + - "null" + remotes: + items: + $ref: '#/components/schemas/ServerTransport' + type: + - array + - "null" + repository: + $ref: '#/components/schemas/ServerRepository' + title: + type: string + version: + type: string + websiteUrl: + type: string + required: + - name + - description + - version + type: object + ServerInput: + additionalProperties: false + properties: + isRequired: + type: boolean + name: + type: string + value: + type: string + required: + - name + type: object + ServerListResponse: + additionalProperties: false + properties: + metadata: + $ref: '#/components/schemas/ListMetadata' + servers: + items: + $ref: '#/components/schemas/ServerResponse' + type: + - array + - "null" + required: + - servers + - metadata + type: object + ServerPackage: + additionalProperties: false + properties: + environmentVariables: + items: + $ref: '#/components/schemas/ServerInput' + type: + - array + - "null" + fileSha256: + type: string + identifier: + type: string + packageArguments: + items: + $ref: '#/components/schemas/ServerArgument' + type: + - array + - "null" + registryBaseUrl: + type: string + registryType: + type: string + runtimeArguments: + items: + $ref: '#/components/schemas/ServerArgument' + type: + - array + - "null" + runtimeHint: + type: string + transport: + $ref: '#/components/schemas/ServerTransport' + version: + type: string + required: + - registryType + - identifier + - version + - transport + type: object + ServerRepository: + additionalProperties: false + properties: + id: + type: string + source: + type: string + subfolder: + type: string + url: + type: string + required: + - url + type: object + ServerResponse: + additionalProperties: false + properties: + _meta: + $ref: '#/components/schemas/ResponseMeta' + server: + $ref: '#/components/schemas/ServerDetail' + required: + - server + type: object + ServerTransport: + additionalProperties: false + properties: + headers: + items: + $ref: '#/components/schemas/ServerInput' + type: + - array + - "null" + type: + type: string + url: + type: string + required: + - type + type: object + Skill: + additionalProperties: false + properties: + apiVersion: + type: string + kind: + type: string + metadata: + $ref: '#/components/schemas/ObjectMeta' + spec: + $ref: '#/components/schemas/SkillSpec' + status: + $ref: '#/components/schemas/SkillStatus' + required: + - metadata + - spec + - apiVersion + - kind + type: object + SkillResolvedSource: + additionalProperties: false + properties: + commit: + type: string + type: object + SkillSource: + additionalProperties: false + properties: + repository: + $ref: '#/components/schemas/Repository' + type: object + SkillSpec: + additionalProperties: false + properties: + description: + type: string + iconUrl: + type: string + source: + $ref: '#/components/schemas/SkillSource' + title: + type: string + type: object + SkillStatus: + additionalProperties: false + properties: + conditions: + items: + $ref: '#/components/schemas/Condition' + type: + - array + - "null" + details: {} + resolvedSource: + $ref: '#/components/schemas/SkillResolvedSource' + type: object + Status: + additionalProperties: false + properties: + conditions: + items: + $ref: '#/components/schemas/Condition' + type: + - array + - "null" + details: {} + type: object + VersionBody: + additionalProperties: false + properties: + build_time: + description: Build timestamp + examples: + - "2025-10-14T12:00:00Z" + type: string + git_commit: + description: Git commit SHA + examples: + - abc123d + type: string + version: + description: Application version + examples: + - v1.0.0 + type: string + required: + - version + - git_commit + - build_time + type: object +info: + description: AgentRegistry API for managing MCP servers, agents, skills, and deployments. + title: AgentRegistry + version: dev +openapi: 3.1.0 +paths: + /plugin-marketplace/marketplace.json: + get: + description: Read-only listing of resolved plugins in the Claude Code marketplace.json + format. + operationId: plugin-marketplace-get + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/MarketplaceResponse' + description: OK + default: + content: + application/problem+json: + schema: + $ref: '#/components/schemas/ErrorModel' + description: Error + summary: Get the plugin marketplace (Claude Code marketplace.json compatibility) + tags: + - plugins + /v0.1/servers: + get: + description: Read-only listing of registered MCP servers in the official MCP + Registry server.json format. + operationId: mcp-registry-list-servers + parameters: + - description: Opaque pagination cursor from a prior response. + explode: false + in: query + name: cursor + schema: + description: Opaque pagination cursor from a prior response. + type: string + - description: Max servers to return (capped at 100). + explode: false + in: query + name: limit + schema: + description: Max servers to return (capped at 100). + format: int64 + type: integer + - description: Substring match on the server name. + explode: false + in: query + name: search + schema: + description: Substring match on the server name. + type: string + - description: RFC3339 timestamp; only servers updated at or after this time. + explode: false + in: query + name: updated_since + schema: + description: RFC3339 timestamp; only servers updated at or after this time. + type: string + - description: '''latest'' (default) or a specific version tag.' + explode: false + in: query + name: version + schema: + description: '''latest'' (default) or a specific version tag.' + type: string + - description: Include servers pending deletion. + explode: false + in: query + name: include_deleted + schema: + description: Include servers pending deletion. + type: boolean + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/ServerListResponse' + description: OK + default: + content: + application/problem+json: + schema: + $ref: '#/components/schemas/ErrorModel' + description: Error + summary: List MCP servers (MCP Registry v0.1 compatibility) + tags: + - servers + /v0.1/servers/{serverName}/versions: + get: + operationId: mcp-registry-list-server-versions + parameters: + - description: URL-encoded '/' server name. + in: path + name: serverName + required: true + schema: + description: URL-encoded '/' server name. + type: string + - explode: false + in: query + name: cursor + schema: + type: string + - explode: false + in: query + name: limit + schema: + format: int64 + type: integer + - explode: false + in: query + name: include_deleted + schema: + type: boolean + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/ServerListResponse' + description: OK + default: + content: + application/problem+json: + schema: + $ref: '#/components/schemas/ErrorModel' + description: Error + summary: List versions of an MCP server (MCP Registry v0.1 compatibility) + tags: + - servers + /v0.1/servers/{serverName}/versions/{version}: + get: + operationId: mcp-registry-get-server-version + parameters: + - description: URL-encoded '/' server name. + in: path + name: serverName + required: true + schema: + description: URL-encoded '/' server name. + type: string + - description: A specific version tag, or 'latest'. + in: path + name: version + required: true + schema: + description: A specific version tag, or 'latest'. + type: string + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/ServerResponse' + description: OK + default: + content: + application/problem+json: + schema: + $ref: '#/components/schemas/ErrorModel' + description: Error + summary: Get a single MCP server version (MCP Registry v0.1 compatibility) + tags: + - servers + /v0/agents: + get: + operationId: list-agents + parameters: + - description: Namespace (defaults to 'default'; 'all' lists across all namespaces). + explode: false + in: query + name: namespace + schema: + description: Namespace (defaults to 'default'; 'all' lists across all namespaces). + type: string + - description: Max items to return (default 50). + explode: false + in: query + name: limit + schema: + default: 50 + description: Max items to return (default 50). + format: int64 + type: integer + - description: Opaque pagination cursor. + explode: false + in: query + name: cursor + schema: + description: Opaque pagination cursor. + type: string + - description: 'Label selector: key=value,key2=value2.' + explode: false + in: query + name: labels + schema: + description: 'Label selector: key=value,key2=value2.' + type: string + - description: Restrict the result set to one tag value (tagged artifact kinds + only). + explode: false + in: query + name: tag + schema: + description: Restrict the result set to one tag value (tagged artifact kinds + only). + type: string + - description: Only return the literal latest tag per (namespace, name). Equivalent + to tag=latest for tagged kinds. + explode: false + in: query + name: latestOnly + schema: + description: Only return the literal latest tag per (namespace, name). Equivalent + to tag=latest for tagged kinds. + type: boolean + - description: Include rows with a deletionTimestamp. + explode: false + in: query + name: includeTerminating + schema: + description: Include rows with a deletionTimestamp. + type: boolean + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/ListOutputAgentBody' + description: OK + default: + content: + application/problem+json: + schema: + $ref: '#/components/schemas/ErrorModel' + description: Error + summary: List Agent (scoped by ?namespace) + /v0/agents/{name}: + get: + operationId: get-latest-agent + parameters: + - description: Namespace (internal; defaults to 'default'). + explode: false + in: query + name: namespace + schema: + description: Namespace (internal; defaults to 'default'). + type: string + - in: path + name: name + required: true + schema: + type: string + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/Agent' + description: OK + default: + content: + application/problem+json: + schema: + $ref: '#/components/schemas/ErrorModel' + description: Error + summary: Get the latest Agent + /v0/agents/{name}/{tag}: + delete: + operationId: delete-agent + parameters: + - description: Namespace (internal; defaults to 'default'). + explode: false + in: query + name: namespace + schema: + description: Namespace (internal; defaults to 'default'). + type: string + - in: path + name: name + required: true + schema: + type: string + - in: path + name: tag + required: true + schema: + type: string + responses: + "204": + description: No Content + default: + content: + application/problem+json: + schema: + $ref: '#/components/schemas/ErrorModel' + description: Error + summary: 'Delete a Agent (soft-delete: sets deletionTimestamp)' + get: + operationId: get-agent + parameters: + - description: Namespace (internal; defaults to 'default'). + explode: false + in: query + name: namespace + schema: + description: Namespace (internal; defaults to 'default'). + type: string + - in: path + name: name + required: true + schema: + type: string + - in: path + name: tag + required: true + schema: + type: string + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/Agent' + description: OK + default: + content: + application/problem+json: + schema: + $ref: '#/components/schemas/ErrorModel' + description: Error + summary: Get a Agent by name and tag + /v0/agents/{name}/tags: + get: + operationId: list-tags-agent + parameters: + - description: Namespace (internal; defaults to 'default'). + explode: false + in: query + name: namespace + schema: + description: Namespace (internal; defaults to 'default'). + type: string + - in: path + name: name + required: true + schema: + type: string + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/ListOutputAgentBody' + description: OK + default: + content: + application/problem+json: + schema: + $ref: '#/components/schemas/ErrorModel' + description: Error + summary: List all tags of a Agent + /v0/apply: + delete: + operationId: delete-batch + parameters: + - description: Run validation without mutating the store. Defaults to false. + explode: false + in: query + name: dryRun + schema: + description: Run validation without mutating the store. Defaults to false. + type: boolean + requestBody: + content: + application/yaml: + schema: + contentMediaType: application/octet-stream + format: binary + type: string + required: true + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/ApplyResultsResponse' + description: OK + default: + content: + application/problem+json: + schema: + $ref: '#/components/schemas/ErrorModel' + description: Error + summary: Delete v1alpha1 resources identified by a multi-doc YAML stream + post: + operationId: apply-batch + parameters: + - description: Run validation without mutating the store. Defaults to false. + explode: false + in: query + name: dryRun + schema: + description: Run validation without mutating the store. Defaults to false. + type: boolean + requestBody: + content: + application/yaml: + schema: + contentMediaType: application/octet-stream + format: binary + type: string + required: true + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/ApplyResultsResponse' + description: OK + default: + content: + application/problem+json: + schema: + $ref: '#/components/schemas/ErrorModel' + description: Error + summary: Apply a multi-doc YAML stream of v1alpha1 resources + /v0/deployments: + get: + operationId: list-deployments + parameters: + - description: Namespace (defaults to 'default'; 'all' lists across all namespaces). + explode: false + in: query + name: namespace + schema: + description: Namespace (defaults to 'default'; 'all' lists across all namespaces). + type: string + - description: Max items to return (default 50). + explode: false + in: query + name: limit + schema: + default: 50 + description: Max items to return (default 50). + format: int64 + type: integer + - description: Opaque pagination cursor. + explode: false + in: query + name: cursor + schema: + description: Opaque pagination cursor. + type: string + - description: 'Label selector: key=value,key2=value2.' + explode: false + in: query + name: labels + schema: + description: 'Label selector: key=value,key2=value2.' + type: string + - description: Restrict the result set to one tag value (tagged artifact kinds + only). + explode: false + in: query + name: tag + schema: + description: Restrict the result set to one tag value (tagged artifact kinds + only). + type: string + - description: Only return the literal latest tag per (namespace, name). Equivalent + to tag=latest for tagged kinds. + explode: false + in: query + name: latestOnly + schema: + description: Only return the literal latest tag per (namespace, name). Equivalent + to tag=latest for tagged kinds. + type: boolean + - description: Include rows with a deletionTimestamp. + explode: false + in: query + name: includeTerminating + schema: + description: Include rows with a deletionTimestamp. + type: boolean + - description: 'Deployment origin filter: managed or discovered.' + explode: false + in: query + name: origin + schema: + description: 'Deployment origin filter: managed or discovered.' + type: string + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/ListOutputDeploymentBody' + description: OK + default: + content: + application/problem+json: + schema: + $ref: '#/components/schemas/ErrorModel' + description: Error + summary: List Deployment (scoped by ?namespace) + /v0/deployments/{name}: + delete: + operationId: delete-deployment + parameters: + - description: Namespace (internal; defaults to 'default'). + explode: false + in: query + name: namespace + schema: + description: Namespace (internal; defaults to 'default'). + type: string + - in: path + name: name + required: true + schema: + type: string + responses: + "204": + description: No Content + default: + content: + application/problem+json: + schema: + $ref: '#/components/schemas/ErrorModel' + description: Error + summary: 'Delete a Deployment (soft-delete: sets deletionTimestamp)' + get: + operationId: get-latest-deployment + parameters: + - description: Namespace (internal; defaults to 'default'). + explode: false + in: query + name: namespace + schema: + description: Namespace (internal; defaults to 'default'). + type: string + - in: path + name: name + required: true + schema: + type: string + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/Deployment' + description: OK + default: + content: + application/problem+json: + schema: + $ref: '#/components/schemas/ErrorModel' + description: Error + summary: Get the latest Deployment + put: + operationId: apply-deployment + parameters: + - description: Namespace (internal; defaults to 'default'). + explode: false + in: query + name: namespace + schema: + description: Namespace (internal; defaults to 'default'). + type: string + - in: path + name: name + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Deployment' + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/Deployment' + description: OK + default: + content: + application/problem+json: + schema: + $ref: '#/components/schemas/ErrorModel' + description: Error + summary: Apply a Deployment (idempotent upsert) + /v0/health: + get: + description: Check the health status of the API + operationId: get-health-v0 + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/HealthBody' + description: OK + default: + content: + application/problem+json: + schema: + $ref: '#/components/schemas/ErrorModel' + description: Error + summary: Health check + tags: + - health + /v0/mcpservers: + get: + operationId: list-mcpservers + parameters: + - description: Namespace (defaults to 'default'; 'all' lists across all namespaces). + explode: false + in: query + name: namespace + schema: + description: Namespace (defaults to 'default'; 'all' lists across all namespaces). + type: string + - description: Max items to return (default 50). + explode: false + in: query + name: limit + schema: + default: 50 + description: Max items to return (default 50). + format: int64 + type: integer + - description: Opaque pagination cursor. + explode: false + in: query + name: cursor + schema: + description: Opaque pagination cursor. + type: string + - description: 'Label selector: key=value,key2=value2.' + explode: false + in: query + name: labels + schema: + description: 'Label selector: key=value,key2=value2.' + type: string + - description: Restrict the result set to one tag value (tagged artifact kinds + only). + explode: false + in: query + name: tag + schema: + description: Restrict the result set to one tag value (tagged artifact kinds + only). + type: string + - description: Only return the literal latest tag per (namespace, name). Equivalent + to tag=latest for tagged kinds. + explode: false + in: query + name: latestOnly + schema: + description: Only return the literal latest tag per (namespace, name). Equivalent + to tag=latest for tagged kinds. + type: boolean + - description: Include rows with a deletionTimestamp. + explode: false + in: query + name: includeTerminating + schema: + description: Include rows with a deletionTimestamp. + type: boolean + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/ListOutputMCPServerBody' + description: OK + default: + content: + application/problem+json: + schema: + $ref: '#/components/schemas/ErrorModel' + description: Error + summary: List MCPServer (scoped by ?namespace) + /v0/mcpservers/{name}: + get: + operationId: get-latest-mcpserver + parameters: + - description: Namespace (internal; defaults to 'default'). + explode: false + in: query + name: namespace + schema: + description: Namespace (internal; defaults to 'default'). + type: string + - in: path + name: name + required: true + schema: + type: string + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/MCPServer' + description: OK + default: + content: + application/problem+json: + schema: + $ref: '#/components/schemas/ErrorModel' + description: Error + summary: Get the latest MCPServer + /v0/mcpservers/{name}/{tag}: + delete: + operationId: delete-mcpserver + parameters: + - description: Namespace (internal; defaults to 'default'). + explode: false + in: query + name: namespace + schema: + description: Namespace (internal; defaults to 'default'). + type: string + - in: path + name: name + required: true + schema: + type: string + - in: path + name: tag + required: true + schema: + type: string + responses: + "204": + description: No Content + default: + content: + application/problem+json: + schema: + $ref: '#/components/schemas/ErrorModel' + description: Error + summary: 'Delete a MCPServer (soft-delete: sets deletionTimestamp)' + get: + operationId: get-mcpserver + parameters: + - description: Namespace (internal; defaults to 'default'). + explode: false + in: query + name: namespace + schema: + description: Namespace (internal; defaults to 'default'). + type: string + - in: path + name: name + required: true + schema: + type: string + - in: path + name: tag + required: true + schema: + type: string + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/MCPServer' + description: OK + default: + content: + application/problem+json: + schema: + $ref: '#/components/schemas/ErrorModel' + description: Error + summary: Get a MCPServer by name and tag + /v0/mcpservers/{name}/tags: + get: + operationId: list-tags-mcpserver + parameters: + - description: Namespace (internal; defaults to 'default'). + explode: false + in: query + name: namespace + schema: + description: Namespace (internal; defaults to 'default'). + type: string + - in: path + name: name + required: true + schema: + type: string + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/ListOutputMCPServerBody' + description: OK + default: + content: + application/problem+json: + schema: + $ref: '#/components/schemas/ErrorModel' + description: Error + summary: List all tags of a MCPServer + /v0/models: + get: + operationId: list-models + parameters: + - description: Namespace (defaults to 'default'; 'all' lists across all namespaces). + explode: false + in: query + name: namespace + schema: + description: Namespace (defaults to 'default'; 'all' lists across all namespaces). + type: string + - description: Max items to return (default 50). + explode: false + in: query + name: limit + schema: + default: 50 + description: Max items to return (default 50). + format: int64 + type: integer + - description: Opaque pagination cursor. + explode: false + in: query + name: cursor + schema: + description: Opaque pagination cursor. + type: string + - description: 'Label selector: key=value,key2=value2.' + explode: false + in: query + name: labels + schema: + description: 'Label selector: key=value,key2=value2.' + type: string + - description: Restrict the result set to one tag value (tagged artifact kinds + only). + explode: false + in: query + name: tag + schema: + description: Restrict the result set to one tag value (tagged artifact kinds + only). + type: string + - description: Only return the literal latest tag per (namespace, name). Equivalent + to tag=latest for tagged kinds. + explode: false + in: query + name: latestOnly + schema: + description: Only return the literal latest tag per (namespace, name). Equivalent + to tag=latest for tagged kinds. + type: boolean + - description: Include rows with a deletionTimestamp. + explode: false + in: query + name: includeTerminating + schema: + description: Include rows with a deletionTimestamp. + type: boolean + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/ListOutputModelBody' + description: OK + default: + content: + application/problem+json: + schema: + $ref: '#/components/schemas/ErrorModel' + description: Error + summary: List Model (scoped by ?namespace) + /v0/models/{name}: + get: + operationId: get-latest-model + parameters: + - description: Namespace (internal; defaults to 'default'). + explode: false + in: query + name: namespace + schema: + description: Namespace (internal; defaults to 'default'). + type: string + - in: path + name: name + required: true + schema: + type: string + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/Model' + description: OK + default: + content: + application/problem+json: + schema: + $ref: '#/components/schemas/ErrorModel' + description: Error + summary: Get the latest Model + /v0/models/{name}/{tag}: + delete: + operationId: delete-model + parameters: + - description: Namespace (internal; defaults to 'default'). + explode: false + in: query + name: namespace + schema: + description: Namespace (internal; defaults to 'default'). + type: string + - in: path + name: name + required: true + schema: + type: string + - in: path + name: tag + required: true + schema: + type: string + responses: + "204": + description: No Content + default: + content: + application/problem+json: + schema: + $ref: '#/components/schemas/ErrorModel' + description: Error + summary: 'Delete a Model (soft-delete: sets deletionTimestamp)' + get: + operationId: get-model + parameters: + - description: Namespace (internal; defaults to 'default'). + explode: false + in: query + name: namespace + schema: + description: Namespace (internal; defaults to 'default'). + type: string + - in: path + name: name + required: true + schema: + type: string + - in: path + name: tag + required: true + schema: + type: string + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/Model' + description: OK + default: + content: + application/problem+json: + schema: + $ref: '#/components/schemas/ErrorModel' + description: Error + summary: Get a Model by name and tag + /v0/models/{name}/tags: + get: + operationId: list-tags-model + parameters: + - description: Namespace (internal; defaults to 'default'). + explode: false + in: query + name: namespace + schema: + description: Namespace (internal; defaults to 'default'). + type: string + - in: path + name: name + required: true + schema: + type: string + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/ListOutputModelBody' + description: OK + default: + content: + application/problem+json: + schema: + $ref: '#/components/schemas/ErrorModel' + description: Error + summary: List all tags of a Model + /v0/ping: + get: + description: Simple ping endpoint + operationId: ping-v0 + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/PingBody' + description: OK + default: + content: + application/problem+json: + schema: + $ref: '#/components/schemas/ErrorModel' + description: Error + summary: Ping + tags: + - ping + /v0/plugins: + get: + operationId: list-plugins + parameters: + - description: Namespace (defaults to 'default'; 'all' lists across all namespaces). + explode: false + in: query + name: namespace + schema: + description: Namespace (defaults to 'default'; 'all' lists across all namespaces). + type: string + - description: Max items to return (default 50). + explode: false + in: query + name: limit + schema: + default: 50 + description: Max items to return (default 50). + format: int64 + type: integer + - description: Opaque pagination cursor. + explode: false + in: query + name: cursor + schema: + description: Opaque pagination cursor. + type: string + - description: 'Label selector: key=value,key2=value2.' + explode: false + in: query + name: labels + schema: + description: 'Label selector: key=value,key2=value2.' + type: string + - description: Restrict the result set to one tag value (tagged artifact kinds + only). + explode: false + in: query + name: tag + schema: + description: Restrict the result set to one tag value (tagged artifact kinds + only). + type: string + - description: Only return the literal latest tag per (namespace, name). Equivalent + to tag=latest for tagged kinds. + explode: false + in: query + name: latestOnly + schema: + description: Only return the literal latest tag per (namespace, name). Equivalent + to tag=latest for tagged kinds. + type: boolean + - description: Include rows with a deletionTimestamp. + explode: false + in: query + name: includeTerminating + schema: + description: Include rows with a deletionTimestamp. + type: boolean + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/ListOutputPluginBody' + description: OK + default: + content: + application/problem+json: + schema: + $ref: '#/components/schemas/ErrorModel' + description: Error + summary: List Plugin (scoped by ?namespace) + /v0/plugins/{name}: + get: + operationId: get-latest-plugin + parameters: + - description: Namespace (internal; defaults to 'default'). + explode: false + in: query + name: namespace + schema: + description: Namespace (internal; defaults to 'default'). + type: string + - in: path + name: name + required: true + schema: + type: string + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/Plugin' + description: OK + default: + content: + application/problem+json: + schema: + $ref: '#/components/schemas/ErrorModel' + description: Error + summary: Get the latest Plugin + /v0/plugins/{name}/{tag}: + delete: + operationId: delete-plugin + parameters: + - description: Namespace (internal; defaults to 'default'). + explode: false + in: query + name: namespace + schema: + description: Namespace (internal; defaults to 'default'). + type: string + - in: path + name: name + required: true + schema: + type: string + - in: path + name: tag + required: true + schema: + type: string + responses: + "204": + description: No Content + default: + content: + application/problem+json: + schema: + $ref: '#/components/schemas/ErrorModel' + description: Error + summary: 'Delete a Plugin (soft-delete: sets deletionTimestamp)' + get: + operationId: get-plugin + parameters: + - description: Namespace (internal; defaults to 'default'). + explode: false + in: query + name: namespace + schema: + description: Namespace (internal; defaults to 'default'). + type: string + - in: path + name: name + required: true + schema: + type: string + - in: path + name: tag + required: true + schema: + type: string + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/Plugin' + description: OK + default: + content: + application/problem+json: + schema: + $ref: '#/components/schemas/ErrorModel' + description: Error + summary: Get a Plugin by name and tag + /v0/plugins/{name}/tags: + get: + operationId: list-tags-plugin + parameters: + - description: Namespace (internal; defaults to 'default'). + explode: false + in: query + name: namespace + schema: + description: Namespace (internal; defaults to 'default'). + type: string + - in: path + name: name + required: true + schema: + type: string + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/ListOutputPluginBody' + description: OK + default: + content: + application/problem+json: + schema: + $ref: '#/components/schemas/ErrorModel' + description: Error + summary: List all tags of a Plugin + /v0/prompts: + get: + operationId: list-prompts + parameters: + - description: Namespace (defaults to 'default'; 'all' lists across all namespaces). + explode: false + in: query + name: namespace + schema: + description: Namespace (defaults to 'default'; 'all' lists across all namespaces). + type: string + - description: Max items to return (default 50). + explode: false + in: query + name: limit + schema: + default: 50 + description: Max items to return (default 50). + format: int64 + type: integer + - description: Opaque pagination cursor. + explode: false + in: query + name: cursor + schema: + description: Opaque pagination cursor. + type: string + - description: 'Label selector: key=value,key2=value2.' + explode: false + in: query + name: labels + schema: + description: 'Label selector: key=value,key2=value2.' + type: string + - description: Restrict the result set to one tag value (tagged artifact kinds + only). + explode: false + in: query + name: tag + schema: + description: Restrict the result set to one tag value (tagged artifact kinds + only). + type: string + - description: Only return the literal latest tag per (namespace, name). Equivalent + to tag=latest for tagged kinds. + explode: false + in: query + name: latestOnly + schema: + description: Only return the literal latest tag per (namespace, name). Equivalent + to tag=latest for tagged kinds. + type: boolean + - description: Include rows with a deletionTimestamp. + explode: false + in: query + name: includeTerminating + schema: + description: Include rows with a deletionTimestamp. + type: boolean + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/ListOutputPromptBody' + description: OK + default: + content: + application/problem+json: + schema: + $ref: '#/components/schemas/ErrorModel' + description: Error + summary: List Prompt (scoped by ?namespace) + /v0/prompts/{name}: + get: + operationId: get-latest-prompt + parameters: + - description: Namespace (internal; defaults to 'default'). + explode: false + in: query + name: namespace + schema: + description: Namespace (internal; defaults to 'default'). + type: string + - in: path + name: name + required: true + schema: + type: string + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/Prompt' + description: OK + default: + content: + application/problem+json: + schema: + $ref: '#/components/schemas/ErrorModel' + description: Error + summary: Get the latest Prompt + /v0/prompts/{name}/{tag}: + delete: + operationId: delete-prompt + parameters: + - description: Namespace (internal; defaults to 'default'). + explode: false + in: query + name: namespace + schema: + description: Namespace (internal; defaults to 'default'). + type: string + - in: path + name: name + required: true + schema: + type: string + - in: path + name: tag + required: true + schema: + type: string + responses: + "204": + description: No Content + default: + content: + application/problem+json: + schema: + $ref: '#/components/schemas/ErrorModel' + description: Error + summary: 'Delete a Prompt (soft-delete: sets deletionTimestamp)' + get: + operationId: get-prompt + parameters: + - description: Namespace (internal; defaults to 'default'). + explode: false + in: query + name: namespace + schema: + description: Namespace (internal; defaults to 'default'). + type: string + - in: path + name: name + required: true + schema: + type: string + - in: path + name: tag + required: true + schema: + type: string + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/Prompt' + description: OK + default: + content: + application/problem+json: + schema: + $ref: '#/components/schemas/ErrorModel' + description: Error + summary: Get a Prompt by name and tag + /v0/prompts/{name}/tags: + get: + operationId: list-tags-prompt + parameters: + - description: Namespace (internal; defaults to 'default'). + explode: false + in: query + name: namespace + schema: + description: Namespace (internal; defaults to 'default'). + type: string + - in: path + name: name + required: true + schema: + type: string + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/ListOutputPromptBody' + description: OK + default: + content: + application/problem+json: + schema: + $ref: '#/components/schemas/ErrorModel' + description: Error + summary: List all tags of a Prompt + /v0/runtimes: + get: + operationId: list-runtimes + parameters: + - description: Namespace (defaults to 'default'; 'all' lists across all namespaces). + explode: false + in: query + name: namespace + schema: + description: Namespace (defaults to 'default'; 'all' lists across all namespaces). + type: string + - description: Max items to return (default 50). + explode: false + in: query + name: limit + schema: + default: 50 + description: Max items to return (default 50). + format: int64 + type: integer + - description: Opaque pagination cursor. + explode: false + in: query + name: cursor + schema: + description: Opaque pagination cursor. + type: string + - description: 'Label selector: key=value,key2=value2.' + explode: false + in: query + name: labels + schema: + description: 'Label selector: key=value,key2=value2.' + type: string + - description: Restrict the result set to one tag value (tagged artifact kinds + only). + explode: false + in: query + name: tag + schema: + description: Restrict the result set to one tag value (tagged artifact kinds + only). + type: string + - description: Only return the literal latest tag per (namespace, name). Equivalent + to tag=latest for tagged kinds. + explode: false + in: query + name: latestOnly + schema: + description: Only return the literal latest tag per (namespace, name). Equivalent + to tag=latest for tagged kinds. + type: boolean + - description: Include rows with a deletionTimestamp. + explode: false + in: query + name: includeTerminating + schema: + description: Include rows with a deletionTimestamp. + type: boolean + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/ListOutputRuntimeBody' + description: OK + default: + content: + application/problem+json: + schema: + $ref: '#/components/schemas/ErrorModel' + description: Error + summary: List Runtime (scoped by ?namespace) + /v0/runtimes/{name}: + delete: + operationId: delete-runtime + parameters: + - description: Namespace (internal; defaults to 'default'). + explode: false + in: query + name: namespace + schema: + description: Namespace (internal; defaults to 'default'). + type: string + - in: path + name: name + required: true + schema: + type: string + responses: + "204": + description: No Content + default: + content: + application/problem+json: + schema: + $ref: '#/components/schemas/ErrorModel' + description: Error + summary: 'Delete a Runtime (soft-delete: sets deletionTimestamp)' + get: + operationId: get-latest-runtime + parameters: + - description: Namespace (internal; defaults to 'default'). + explode: false + in: query + name: namespace + schema: + description: Namespace (internal; defaults to 'default'). + type: string + - in: path + name: name + required: true + schema: + type: string + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/Runtime' + description: OK + default: + content: + application/problem+json: + schema: + $ref: '#/components/schemas/ErrorModel' + description: Error + summary: Get the latest Runtime + put: + operationId: apply-runtime + parameters: + - description: Namespace (internal; defaults to 'default'). + explode: false + in: query + name: namespace + schema: + description: Namespace (internal; defaults to 'default'). + type: string + - in: path + name: name + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Runtime' + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/Runtime' + description: OK + default: + content: + application/problem+json: + schema: + $ref: '#/components/schemas/ErrorModel' + description: Error + summary: Apply a Runtime (idempotent upsert) + /v0/secrets: + get: + operationId: list-secrets + parameters: + - description: Namespace (defaults to 'default'; 'all' lists across all namespaces). + explode: false + in: query + name: namespace + schema: + description: Namespace (defaults to 'default'; 'all' lists across all namespaces). + type: string + - description: Max items to return (default 50). + explode: false + in: query + name: limit + schema: + default: 50 + description: Max items to return (default 50). + format: int64 + type: integer + - description: Opaque pagination cursor. + explode: false + in: query + name: cursor + schema: + description: Opaque pagination cursor. + type: string + - description: 'Label selector: key=value,key2=value2.' + explode: false + in: query + name: labels + schema: + description: 'Label selector: key=value,key2=value2.' + type: string + - description: Restrict the result set to one tag value (tagged artifact kinds + only). + explode: false + in: query + name: tag + schema: + description: Restrict the result set to one tag value (tagged artifact kinds + only). + type: string + - description: Only return the literal latest tag per (namespace, name). Equivalent + to tag=latest for tagged kinds. + explode: false + in: query + name: latestOnly + schema: + description: Only return the literal latest tag per (namespace, name). Equivalent + to tag=latest for tagged kinds. + type: boolean + - description: Include rows with a deletionTimestamp. + explode: false + in: query + name: includeTerminating + schema: + description: Include rows with a deletionTimestamp. + type: boolean + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/ListOutputSecretBody' + description: OK + default: + content: + application/problem+json: + schema: + $ref: '#/components/schemas/ErrorModel' + description: Error + summary: List Secret (scoped by ?namespace) + /v0/secrets/{name}: + delete: + operationId: delete-secret + parameters: + - description: Namespace (internal; defaults to 'default'). + explode: false + in: query + name: namespace + schema: + description: Namespace (internal; defaults to 'default'). + type: string + - in: path + name: name + required: true + schema: + type: string + responses: + "204": + description: No Content + default: + content: + application/problem+json: + schema: + $ref: '#/components/schemas/ErrorModel' + description: Error + summary: 'Delete a Secret (soft-delete: sets deletionTimestamp)' + get: + operationId: get-latest-secret + parameters: + - description: Namespace (internal; defaults to 'default'). + explode: false + in: query + name: namespace + schema: + description: Namespace (internal; defaults to 'default'). + type: string + - in: path + name: name + required: true + schema: + type: string + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/Secret' + description: OK + default: + content: + application/problem+json: + schema: + $ref: '#/components/schemas/ErrorModel' + description: Error + summary: Get the latest Secret + put: + operationId: apply-secret + parameters: + - description: Namespace (internal; defaults to 'default'). + explode: false + in: query + name: namespace + schema: + description: Namespace (internal; defaults to 'default'). + type: string + - in: path + name: name + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/Secret' + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/Secret' + description: OK + default: + content: + application/problem+json: + schema: + $ref: '#/components/schemas/ErrorModel' + description: Error + summary: Apply a Secret (idempotent upsert) + /v0/skills: + get: + operationId: list-skills + parameters: + - description: Namespace (defaults to 'default'; 'all' lists across all namespaces). + explode: false + in: query + name: namespace + schema: + description: Namespace (defaults to 'default'; 'all' lists across all namespaces). + type: string + - description: Max items to return (default 50). + explode: false + in: query + name: limit + schema: + default: 50 + description: Max items to return (default 50). + format: int64 + type: integer + - description: Opaque pagination cursor. + explode: false + in: query + name: cursor + schema: + description: Opaque pagination cursor. + type: string + - description: 'Label selector: key=value,key2=value2.' + explode: false + in: query + name: labels + schema: + description: 'Label selector: key=value,key2=value2.' + type: string + - description: Restrict the result set to one tag value (tagged artifact kinds + only). + explode: false + in: query + name: tag + schema: + description: Restrict the result set to one tag value (tagged artifact kinds + only). + type: string + - description: Only return the literal latest tag per (namespace, name). Equivalent + to tag=latest for tagged kinds. + explode: false + in: query + name: latestOnly + schema: + description: Only return the literal latest tag per (namespace, name). Equivalent + to tag=latest for tagged kinds. + type: boolean + - description: Include rows with a deletionTimestamp. + explode: false + in: query + name: includeTerminating + schema: + description: Include rows with a deletionTimestamp. + type: boolean + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/ListOutputSkillBody' + description: OK + default: + content: + application/problem+json: + schema: + $ref: '#/components/schemas/ErrorModel' + description: Error + summary: List Skill (scoped by ?namespace) + /v0/skills/{name}: + get: + operationId: get-latest-skill + parameters: + - description: Namespace (internal; defaults to 'default'). + explode: false + in: query + name: namespace + schema: + description: Namespace (internal; defaults to 'default'). + type: string + - in: path + name: name + required: true + schema: + type: string + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/Skill' + description: OK + default: + content: + application/problem+json: + schema: + $ref: '#/components/schemas/ErrorModel' + description: Error + summary: Get the latest Skill + /v0/skills/{name}/{tag}: + delete: + operationId: delete-skill + parameters: + - description: Namespace (internal; defaults to 'default'). + explode: false + in: query + name: namespace + schema: + description: Namespace (internal; defaults to 'default'). + type: string + - in: path + name: name + required: true + schema: + type: string + - in: path + name: tag + required: true + schema: + type: string + responses: + "204": + description: No Content + default: + content: + application/problem+json: + schema: + $ref: '#/components/schemas/ErrorModel' + description: Error + summary: 'Delete a Skill (soft-delete: sets deletionTimestamp)' + get: + operationId: get-skill + parameters: + - description: Namespace (internal; defaults to 'default'). + explode: false + in: query + name: namespace + schema: + description: Namespace (internal; defaults to 'default'). + type: string + - in: path + name: name + required: true + schema: + type: string + - in: path + name: tag + required: true + schema: + type: string + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/Skill' + description: OK + default: + content: + application/problem+json: + schema: + $ref: '#/components/schemas/ErrorModel' + description: Error + summary: Get a Skill by name and tag + /v0/skills/{name}/tags: + get: + operationId: list-tags-skill + parameters: + - description: Namespace (internal; defaults to 'default'). + explode: false + in: query + name: namespace + schema: + description: Namespace (internal; defaults to 'default'). + type: string + - in: path + name: name + required: true + schema: + type: string + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/ListOutputSkillBody' + description: OK + default: + content: + application/problem+json: + schema: + $ref: '#/components/schemas/ErrorModel' + description: Error + summary: List all tags of a Skill + /v0/version: + get: + description: Returns the version, git commit, and build time of the registry + application + operationId: get-version-v0 + responses: + "200": + content: + application/json: + schema: + $ref: '#/components/schemas/VersionBody' + description: OK + default: + content: + application/problem+json: + schema: + $ref: '#/components/schemas/ErrorModel' + description: Error + summary: Get version information + tags: + - version diff --git a/content/docs/reference/_index.md b/content/docs/reference/_index.md index 474dbd2..0b86561 100644 --- a/content/docs/reference/_index.md +++ b/content/docs/reference/_index.md @@ -1,5 +1,5 @@ --- title: Reference weight: 100 -description: "Reference documentation for agentregistry, including the arctl CLI." +description: "Reference documentation for agentregistry: the arctl CLI, Helm chart values, and the REST API." --- \ No newline at end of file diff --git a/content/docs/reference/api.md b/content/docs/reference/api.md new file mode 100644 index 0000000..1f3cfa6 --- /dev/null +++ b/content/docs/reference/api.md @@ -0,0 +1,15 @@ +--- +title: REST API +weight: 30 +description: "Endpoints, request and response schemas for the agentregistry REST API." +--- + + + +The agentregistry server exposes a REST API for managing agents, MCP servers, +skills, prompts, and deployments. The reference below is rendered from the +server's OpenAPI specification. + +{{< openapi src="ar-docs/openapi.yaml" >}} diff --git a/content/docs/reference/helm.md b/content/docs/reference/helm.md new file mode 100644 index 0000000..81bf56a --- /dev/null +++ b/content/docs/reference/helm.md @@ -0,0 +1,126 @@ +--- +title: Helm values +weight: 20 +description: "Configuration values for the agentregistry Helm chart." +--- + + + +Every value the agentregistry Helm chart accepts, with its type and default. +Override them with `--set key=value` on the install command, or by passing a +values file with `-f`. + +| Key | Type | Default | Description | +|-----|------|---------|-------------| +| affinity | object | `{}` | Affinity rules for pod assignment (overrides preset if set) | +| args | list | `[]` | Override default container args (evaluated as a template) | +| automountServiceAccountToken | bool | `true` | Mount the service account token in the pod | +| command | list | `[]` | Override default container command (evaluated as a template) | +| commonAnnotations | object | `{}` | Annotations to add to all deployed resources | +| commonLabels | object | `{}` | Labels to add to all deployed resources | +| config.agentRegistryMcpPort | string | `"31313"` | Agent Registry MCP server port | +| config.enableRegistryValidation | string | `"false"` | Enable input validation on the registry API | +| config.serverAddress | string | `":8080"` | Listen address for the HTTP server | +| containerSecurityContext.allowPrivilegeEscalation | bool | `false` | Allow privilege escalation | +| containerSecurityContext.capabilities.drop | list | `["ALL"]` | Linux capabilities to drop | +| containerSecurityContext.enabled | bool | `true` | Enable container-level security context | +| containerSecurityContext.readOnlyRootFilesystem | bool | `true` | Mount root filesystem as read-only | +| containerSecurityContext.runAsGroup | int | `1001` | Group ID to run the container as | +| containerSecurityContext.runAsNonRoot | bool | `true` | Prevent running as root | +| containerSecurityContext.runAsUser | int | `1001` | User ID to run the container as | +| containerSecurityContext.seccompProfile.type | string | `"RuntimeDefault"` | Seccomp profile type | +| database.postgres.bundled | object | `{"image":{"name":"postgres","pullPolicy":"IfNotPresent","registry":"docker.io","repository":"library","tag":"18"},"resources":{"limits":{"cpu":"1","memory":"1Gi"},"requests":{"cpu":"250m","memory":"256Mi"}},"storage":"5Gi","storageClass":""}` | Bundled PostgreSQL — dev/eval only. Only consumed when `type: bundled`. | +| database.postgres.bundled.image.name | string | `"postgres"` | Bundled PostgreSQL image name | +| database.postgres.bundled.image.pullPolicy | string | `"IfNotPresent"` | Bundled PostgreSQL image pull policy | +| database.postgres.bundled.image.registry | string | `"docker.io"` | Bundled PostgreSQL image registry | +| database.postgres.bundled.image.repository | string | `"library"` | Bundled PostgreSQL image repository (org/namespace) | +| database.postgres.bundled.image.tag | string | `"18"` | Bundled PostgreSQL image tag | +| database.postgres.bundled.resources | object | `{"limits":{"cpu":"1","memory":"1Gi"},"requests":{"cpu":"250m","memory":"256Mi"}}` | Resource requests/limits for the bundled PostgreSQL container | +| database.postgres.bundled.storage | string | `"5Gi"` | PersistentVolumeClaim size for the bundled PostgreSQL data directory | +| database.postgres.bundled.storageClass | string | `""` | StorageClass for the bundled PostgreSQL PersistentVolumeClaim. Leave empty ("") to use the cluster default StorageClass. | +| database.postgres.external | object | `{"secretRef":{"key":"AGENT_REGISTRY_DATABASE_URL","name":""},"url":""}` | External (BYO) PostgreSQL configuration. Only consumed when `type: external`. | +| database.postgres.external.secretRef | object | `{"key":"AGENT_REGISTRY_DATABASE_URL","name":""}` | Source the connection string from an existing Secret instead of inlining it. Use this when credentials are managed by an external secret store (e.g. AWS Secrets Manager via External Secrets Operator) and synced into the cluster as a Secret. The chart does not create or manage this Secret. Mutually exclusive with `external.url`. On credential rotation, Kubernetes does NOT auto-restart the pod — pair with a controller such as stakater/Reloader if you need automatic restarts on Secret content changes. | +| database.postgres.external.secretRef.key | string | `"AGENT_REGISTRY_DATABASE_URL"` | Key within the Secret that holds the connection string. | +| database.postgres.external.secretRef.name | string | `""` | Name of an existing Secret in the release namespace. Leave empty to disable. | +| database.postgres.external.url | string | `""` | Inline connection string. Mutually exclusive with `external.secretRef.name`. | +| database.postgres.type | string | `"bundled"` | Backend type: "bundled" (deploy the chart's in-cluster dev/eval Postgres pod) or "external" (connect to a Postgres you bring yourself; configure under `external` below). | +| dnsConfig | object | `{}` | DNS configuration for the pod | +| dnsPolicy | string | `""` | DNS policy for the pod | +| extraEnvVars | list | `[]` | Array of extra environment variables for the Agent Registry container. Additive only — cannot override env vars the chart already renders. For credentialed fields use the dedicated knobs (e.g. `database.postgres.external.secretRef`). | +| fullnameOverride | string | `""` | Override the full name of the chart | +| global.imagePullSecrets | list | `[]` | Global Docker registry secret names | +| global.imageRegistry | string | `""` | Global container image registry override | +| hostAliases | list | `[]` | Add custom entries to /etc/hosts | +| image.digest | string | `""` | Agent Registry image digest (overrides tag if set) | +| image.name | string | `"server"` | Agent Registry image name | +| image.pullPolicy | string | `"IfNotPresent"` | Agent Registry image pull policy | +| image.pullSecrets | list | `[]` | Agent Registry image pull secrets | +| image.registry | string | `"ghcr.io"` | Agent Registry image registry | +| image.repository | string | `"agentregistry-dev/agentregistry"` | Agent Registry image repository (org/path, excluding the image name) | +| image.tag | string | `""` | Agent Registry image tag (immutable tags recommended). Leave empty to use .Chart.AppVersion. | +| lifecycleHooks | object | `{}` | Lifecycle hooks for the Agent Registry container | +| livenessProbe.enabled | bool | `true` | Enable liveness probe | +| livenessProbe.failureThreshold | int | `6` | Failure threshold for liveness check | +| livenessProbe.initialDelaySeconds | int | `30` | Initial delay before liveness check | +| livenessProbe.periodSeconds | int | `10` | Period between liveness checks | +| livenessProbe.successThreshold | int | `1` | Success threshold for liveness check | +| livenessProbe.timeoutSeconds | int | `5` | Timeout for the liveness check | +| nameOverride | string | `""` | Override the name of the chart | +| nodeAffinityPreset.key | string | `""` | Node label key for affinity | +| nodeAffinityPreset.type | string | `""` | Node affinity preset type (soft or hard) | +| nodeAffinityPreset.values | list | `[]` | Node label values for affinity | +| nodeSelector | object | `{}` | Node labels for pod assignment | +| podAffinityPreset | string | `""` | Pod affinity preset (soft or hard) | +| podAnnotations | object | `{}` | Extra annotations for Agent Registry pods | +| podAntiAffinityPreset | string | `"soft"` | Pod anti-affinity preset (soft or hard) | +| podLabels | object | `{}` | Extra labels for Agent Registry pods | +| podSecurityContext.enabled | bool | `true` | Enable pod-level security context | +| podSecurityContext.fsGroup | int | `1001` | Group ID for the pod filesystem | +| podSecurityContext.fsGroupChangePolicy | string | `"Always"` | Policy for changing fsGroup ownership | +| priorityClassName | string | `""` | Priority class name for the Agent Registry pods | +| rbac.enabled | bool | `true` | Enable RBAC resource creation | +| rbac.watchedNamespaces | list | `[]` | Namespaces Agent Registry is permitted to manage resources in. Empty list grants cluster-wide access via ClusterRole (default). Set to one or more namespaces to create a Role in each and restrict access accordingly. Note: read access to the cluster scoped APIs is always granted via ClusterRole regardless of this setting. | +| readinessProbe.enabled | bool | `true` | Enable readiness probe | +| readinessProbe.failureThreshold | int | `3` | Failure threshold for readiness check | +| readinessProbe.initialDelaySeconds | int | `10` | Initial delay before readiness check | +| readinessProbe.periodSeconds | int | `5` | Period between readiness checks | +| readinessProbe.successThreshold | int | `1` | Success threshold for readiness check | +| readinessProbe.timeoutSeconds | int | `3` | Timeout for the readiness check | +| replicaCount | int | `1` | Number of Agent Registry replicas | +| resources | object | `{"limits":{"cpu":"1","memory":"1Gi"},"requests":{"cpu":"250m","memory":"256Mi"}}` | Resource requests and limits for the Agent Registry container | +| revisionHistoryLimit | int | `10` | Number of old ReplicaSets to retain | +| schedulerName | string | `""` | Name of the scheduler to use | +| secretStore | object | `{"encryptionKeySecretRef":{"key":"SECRET_STORE_ENCRYPTION_KEY","name":""},"type":"Kubernetes"}` | Backend used to persist Secret resource payloads. | +| secretStore.encryptionKeySecretRef | object | `{"key":"SECRET_STORE_ENCRYPTION_KEY","name":""}` | Existing Secret containing the hex-encoded 32-byte AES-256 key for Database. | +| secretStore.encryptionKeySecretRef.key | string | `"SECRET_STORE_ENCRYPTION_KEY"` | Key containing the encryption key. | +| secretStore.encryptionKeySecretRef.name | string | `""` | Name of the Secret in the install namespace. | +| secretStore.type | string | `"Kubernetes"` | "Kubernetes" stores core/v1.Secrets; "Database" encrypts payloads in Postgres. | +| service.annotations | object | `{}` | Service annotations | +| service.clusterIP | string | `""` | Specific cluster IP (set to None for headless) | +| service.externalTrafficPolicy | string | `"Cluster"` | External traffic policy | +| service.loadBalancerIP | string | `""` | LoadBalancer IP | +| service.loadBalancerSourceRanges | list | `[]` | LoadBalancer allowed source ranges | +| service.nodePorts.http | string | `""` | NodePort for HTTP (when type is NodePort) | +| service.nodePorts.mcp | string | `""` | NodePort for MCP (when type is NodePort) | +| service.ports.http | int | `12121` | HTTP port | +| service.ports.mcp | int | `31313` | MCP HTTP port | +| service.sessionAffinity | string | `"None"` | Session affinity (None or ClientIP) | +| service.sessionAffinityConfig | object | `{}` | Session affinity configuration | +| service.targetPorts.http | int | `8080` | HTTP container target port | +| service.targetPorts.mcp | int | `31313` | MCP container target port | +| service.type | string | `"ClusterIP"` | Kubernetes Service type | +| serviceAccount.annotations | object | `{}` | ServiceAccount annotations | +| serviceAccount.automountServiceAccountToken | bool | `true` | Mount API token in the ServiceAccount | +| serviceAccount.create | bool | `true` | Create a dedicated ServiceAccount | +| serviceAccount.name | string | `""` | Override the auto-generated ServiceAccount name | +| startupProbe.enabled | bool | `true` | Enable startup probe | +| startupProbe.failureThreshold | int | `30` | Failure threshold for startup check (controls max startup time) | +| startupProbe.initialDelaySeconds | int | `5` | Initial delay before startup check | +| startupProbe.periodSeconds | int | `5` | Period between startup checks | +| startupProbe.successThreshold | int | `1` | Success threshold for startup check | +| startupProbe.timeoutSeconds | int | `3` | Timeout for the startup check | +| terminationGracePeriodSeconds | string | `""` | Seconds the pod needs to terminate gracefully | +| tolerations | list | `[]` | Tolerations for pod assignment | +| topologySpreadConstraints | list | `[]` | Topology spread constraints for pod assignment | diff --git a/hugo_stats.json b/hugo_stats.json index 8cc6dcb..dcf7711 100644 --- a/hugo_stats.json +++ b/hugo_stats.json @@ -104,6 +104,7 @@ "copy-md-dropdown", "copy-md-dropdown-sep", "copy-md-label", + "copy-md-only", "copy-md-source", "copy-md-split", "copy-md-toggle", @@ -455,6 +456,7 @@ "nav-link", "nav-link-kbd", "nav-links", + "openapi-container", "page-description", "pnf-code", "preview-appbar", @@ -630,6 +632,7 @@ "step-2-verify-the-runtime", "supported-clients", "supported-tools", + "swagger-ui", "tabs-panel-tabs-00-0", "tabs-panel-tabs-00-1", "tabs-panel-tabs-01-0", diff --git a/scripts/generate-api-ref.py b/scripts/generate-api-ref.py new file mode 100644 index 0000000..37d07c1 --- /dev/null +++ b/scripts/generate-api-ref.py @@ -0,0 +1,90 @@ +#!/usr/bin/env python3 +""" +Generate the REST API reference for the agentregistry website. + +Copies the product repo's openapi.yaml into assets/ and writes a page that +renders it with docs-theme-extras' `openapi` shortcode (Swagger UI). + +The spec is copied rather than fetched from GitHub at build time. `src` resolves +through Hugo's `resources.Get`, so the spec is served from the site's own origin +— the page then renders on a runner with no network access, and the shortcode's +build-time parse (which supplies the Copy-as-Markdown summary, since Swagger UI +renders client-side and would otherwise leave that copy empty) cannot be broken +by a slow or unreachable raw.githubusercontent.com. + +openapi.yaml is generated upstream by `make gen-openapi` and guarded by +`make verify`, so it is already trustworthy at any commit on main. + +Usage (from the workflow, or locally): + AGENTREGISTRY_DIR=/path/to/agentregistry \\ + WEBSITE_DIR=/path/to/website \\ + python3 scripts/generate-api-ref.py +""" + +import os +import shutil +from pathlib import Path + +SPEC_SOURCE = Path("openapi.yaml") +SPEC_TARGET = Path("assets") / "ar-docs" / "openapi.yaml" +OUTPUT_PATH = Path("content") / "docs" / "reference" / "api.md" + +PAGE_WEIGHT = 30 + +# deepLinking stays off: it hijacks window.location.hash for Swagger's own +# routing, which breaks the page's normal anchor navigation wherever a Hextra +# TOC is also present. +PAGE = """--- +title: REST API +weight: {weight} +description: "Endpoints, request and response schemas for the agentregistry REST API." +--- + + + +The agentregistry server exposes a REST API for managing agents, MCP servers, +skills, prompts, and deployments. The reference below is rendered from the +server's OpenAPI specification. + +{{{{< openapi src="ar-docs/openapi.yaml" >}}}} +""" + + +def main() -> None: + website_dir = Path(os.environ.get("WEBSITE_DIR", ".")).resolve() + agentregistry_dir = Path(os.environ.get("AGENTREGISTRY_DIR", "agentregistry")).resolve() + + if not agentregistry_dir.is_dir(): + raise SystemExit(f"Error: agentregistry checkout not found at {agentregistry_dir}") + if not (website_dir / "hugo.yaml").exists(): + raise SystemExit(f"Error: {website_dir} does not look like the website repo (no hugo.yaml)") + + spec = agentregistry_dir / SPEC_SOURCE + if not spec.exists(): + raise SystemExit( + f"Error: {spec} not found. It is generated by `make gen-openapi` in the " + "product repo and committed there." + ) + + # A spec that parses but is nearly empty would render as a blank Swagger UI + # with no obvious error, so check it has actual paths before publishing. + text = spec.read_text(encoding="utf-8") + if "paths:" not in text: + raise SystemExit(f"Error: {spec} has no `paths:` section; refusing to publish it.") + + target = website_dir / SPEC_TARGET + target.parent.mkdir(parents=True, exist_ok=True) + shutil.copyfile(spec, target) + + page = website_dir / OUTPUT_PATH + page.parent.mkdir(parents=True, exist_ok=True) + page.write_text(PAGE.format(weight=PAGE_WEIGHT), encoding="utf-8") + + kb = target.stat().st_size // 1024 + print(f" Copied {SPEC_TARGET} ({kb} KB) and generated {OUTPUT_PATH}.") + + +if __name__ == "__main__": + main() diff --git a/scripts/generate-helm-ref.py b/scripts/generate-helm-ref.py new file mode 100644 index 0000000..8ad389f --- /dev/null +++ b/scripts/generate-helm-ref.py @@ -0,0 +1,136 @@ +#!/usr/bin/env python3 +""" +Generate the Helm values reference for the agentregistry website. + +Runs helm-docs against a checkout of the product repo's chart and writes the +values table to content/docs/reference/helm.md. + +Only the values table is published, not the chart's whole README. The README is +written for people browsing the chart repo — it opens with a TL;DR install +one-liner and closes with Maintainers and Source Code — and its install, +database and RBAC narrative would compete with the site's own setup guides. +The values table is the part that is generated from values.yaml, so it is the +part that silently drifts, and it is what a reference page is for. + +helm-docs is driven with our own single-line template (scripts/helm-values.gotmpl) +rather than by slicing the "## Parameters" section out of the rendered README. +Slicing would couple this script to a heading in a template it does not own — +rename that heading upstream and the extraction returns nothing, quietly. + +Usage (from the workflow, or locally): + AGENTREGISTRY_DIR=/path/to/agentregistry \\ + WEBSITE_DIR=/path/to/website \\ + python3 scripts/generate-helm-ref.py +""" + +import os +import re +import subprocess +from pathlib import Path + +OUTPUT_PATH = Path("content") / "docs" / "reference" / "helm.md" +TEMPLATE = Path("scripts") / "helm-values.gotmpl" + +PAGE_WEIGHT = 20 + +FRONT_MATTER = """--- +title: Helm values +weight: {weight} +description: "Configuration values for the agentregistry Helm chart." +--- + + + +Every value the agentregistry Helm chart accepts, with its type and default. +Override them with `--set key=value` on the install command, or by passing a +values file with `-f`. + +""" + + +def render_values(agentregistry_dir: Path, template: Path) -> str: + """Run helm-docs against the chart and return the rendered values table.""" + chart_dir = agentregistry_dir / "charts" / "agentregistry" + if not (chart_dir / "values.yaml").exists(): + raise SystemExit(f"Error: no chart found at {chart_dir}") + + # helm-docs needs a Chart.yaml, which this repo generates from + # Chart-template.yaml and gitignores. Use the product repo's own target so + # the version substitution stays whatever upstream says it is. + subprocess.run(["make", "charts-generate"], check=True, cwd=agentregistry_dir) + + # Run the helm-docs pinned in the product repo's tools module rather than + # whatever happens to be on PATH, so the table's formatting cannot change + # under us between runs. + result = subprocess.run( + [ + "go", "tool", "-modfile=tools/go.mod", "helm-docs", + "--log-level=fatal", + "-c", "./charts/agentregistry", + f"--template-files={template.resolve()}", + "--dry-run", + ], + check=True, + cwd=agentregistry_dir, + capture_output=True, + text=True, + ) + return result.stdout + + +def clean(values: str) -> str: + """Drop helm-docs' own heading and normalize trailing whitespace. + + The `## Values` heading is dropped because the front-matter title already + names the page; keeping it would put a lone redundant entry in the TOC. + """ + values = re.sub(r"^##+ Values\s*\n+", "", values, count=1) + return values.strip() + "\n" + + +def check_table(values: str) -> None: + """Fail loudly if the render is empty or not a table. + + A silent empty render is the failure mode worth guarding: helm-docs exits 0 + when a template produces nothing, so without this the workflow would happily + open a PR deleting every documented value. + """ + rows = [ln for ln in values.split("\n") if ln.startswith("|")] + if len(rows) < 3: + raise SystemExit( + f"Error: helm-docs produced {len(rows)} table rows, expected a full " + "values table. Check scripts/helm-values.gotmpl against the " + "helm-docs version pinned in the product repo." + ) + # Header, separator, and one row per value; every row needs 4 columns. + bad = [r for r in rows if r.count("|") != 5] + if bad: + raise SystemExit( + f"Error: {len(bad)} malformed table row(s), first: {bad[0][:120]}" + ) + + +def main() -> None: + website_dir = Path(os.environ.get("WEBSITE_DIR", ".")).resolve() + agentregistry_dir = Path(os.environ.get("AGENTREGISTRY_DIR", "agentregistry")).resolve() + + if not agentregistry_dir.is_dir(): + raise SystemExit(f"Error: agentregistry checkout not found at {agentregistry_dir}") + if not (website_dir / "hugo.yaml").exists(): + raise SystemExit(f"Error: {website_dir} does not look like the website repo (no hugo.yaml)") + + values = clean(render_values(agentregistry_dir, website_dir / TEMPLATE)) + check_table(values) + + target = website_dir / OUTPUT_PATH + target.parent.mkdir(parents=True, exist_ok=True) + target.write_text(FRONT_MATTER.format(weight=PAGE_WEIGHT) + values, encoding="utf-8") + + rows = sum(1 for ln in values.split("\n") if ln.startswith("|")) - 2 + print(f" Generated {OUTPUT_PATH} ({rows} values).") + + +if __name__ == "__main__": + main() diff --git a/scripts/helm-values.gotmpl b/scripts/helm-values.gotmpl new file mode 100644 index 0000000..30197f9 --- /dev/null +++ b/scripts/helm-values.gotmpl @@ -0,0 +1 @@ +{{ template "chart.valuesSection" . }}