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..a4b9d0f 100644 --- a/.github/workflows/reference-docs.yml +++ b/.github/workflows/reference-docs.yml @@ -1,30 +1,129 @@ -name: Generate CLI Reference +# Regenerates the reference docs from the agentregistry product repo and opens a +# PR with the result. Three sources, one PR: +# +# 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. +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: + reference: + name: Generate reference docs 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 + # 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 + python3 website/scripts/generate-helm-ref.py + python3 website/scripts/generate-api-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 reference docs' + commit-message: | + 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 reference docs from + [`${{ steps.source.outputs.sha }}`](https://github.com/agentregistry-dev/agentregistry/commit/${{ steps.source.outputs.sha }}). + + | 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: | + 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/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/cli/arctl-apply.md b/content/docs/reference/cli/arctl-apply.md index d85ab76..9e3e0d7 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]({{< 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 d618058..2917a2c 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]({{< 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 new file mode 100644 index 0000000..88c8937 --- /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]({{< 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 new file mode 100644 index 0000000..5440345 --- /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]({{< 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 new file mode 100644 index 0000000..0a05b63 --- /dev/null +++ b/content/docs/reference/cli/arctl-completion-powershell.md @@ -0,0 +1,40 @@ +--- +title: arctl completion powershell +weight: 10 +description: "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]({{< 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 new file mode 100644 index 0000000..0240cdb --- /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]({{< 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 cd08829..6190c42 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]({{< 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 new file mode 100644 index 0000000..ca72659 --- /dev/null +++ b/content/docs/reference/cli/arctl-configure-claude-code.md @@ -0,0 +1,44 @@ +--- +title: arctl configure claude-code +weight: 10 +description: "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 + +```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]({{< 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 new file mode 100644 index 0000000..942802e --- /dev/null +++ b/content/docs/reference/cli/arctl-configure-cursor.md @@ -0,0 +1,44 @@ +--- +title: arctl configure cursor +weight: 10 +description: "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 + +```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]({{< 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 new file mode 100644 index 0000000..bf16346 --- /dev/null +++ b/content/docs/reference/cli/arctl-configure-kiro.md @@ -0,0 +1,44 @@ +--- +title: arctl configure kiro +weight: 10 +description: "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 + +```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]({{< 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 new file mode 100644 index 0000000..23cfab7 --- /dev/null +++ b/content/docs/reference/cli/arctl-configure-vscode.md @@ -0,0 +1,44 @@ +--- +title: arctl configure vscode +weight: 10 +description: "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 + +```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]({{< 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 cc8b313..712ab6e 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: "Write the JSON config 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]({{< 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 new file mode 100644 index 0000000..0684ee0 --- /dev/null +++ b/content/docs/reference/cli/arctl-db-migrate-down.md @@ -0,0 +1,35 @@ +--- +title: arctl db migrate down +weight: 10 +description: "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 +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]({{< 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 new file mode 100644 index 0000000..edc5ad2 --- /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]({{< 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 new file mode 100644 index 0000000..be1bb8c --- /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]({{< 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 new file mode 100644 index 0000000..4a04b2e --- /dev/null +++ b/content/docs/reference/cli/arctl-db-migrate-status.md @@ -0,0 +1,38 @@ +--- +title: arctl db migrate status +weight: 10 +description: "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 + +```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]({{< 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 new file mode 100644 index 0000000..a52db8f --- /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]({{< 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 new file mode 100644 index 0000000..58d8c1a --- /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]({{< 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 c372ed3..d5cc2f3 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]({{< 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 4e90573..5ca2fca 100644 --- a/content/docs/reference/cli/arctl-db.md +++ b/content/docs/reference/cli/arctl-db.md @@ -1,21 +1,25 @@ --- title: arctl db -description: "Database operations for the agent registry (migrations, inspection)." weight: 10 +description: "Database operations (migrations, inspection)." --- -Database operations for the agent registry: running, rolling back, and inspecting database migrations. + -## Usage +Work with the agent registry database directly, without starting the server. -```sh -arctl db [command] -``` - -Available sub-commands: `migrate` +Covers schema migrations: apply pending migrations, roll them back, and inspect +which version each registered migration source is on. ## 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]({{< 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 b61948b..0b2d835 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 file." --- -Delete a registry resource. + -**File mode (declarative):** reads resources from a YAML file and sends `DELETE /v0/apply`. +Delete a registry resource by type and name, or from a YAML file. -**Explicit mode:** specify the type and name directly. For taggable artifacts (agents, MCPs, skills, prompts), `--tag` selects an exact tag and defaults to `latest`. +File mode (declarative): reads resources from the YAML file and sends `DELETE /v0/apply`. -Supported types: `agent`, `mcp`, `skill`, `prompt`, `deployment` (plural and uppercase forms also accepted) +```sh +arctl delete -f agent.yaml +``` + +Explicit mode: specify type and name. For taggable artifacts, `--tag` selects an +exact tag and defaults to latest. + +```sh +arctl delete TYPE NAME [--tag TAG] +``` + +`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]({{< 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 06ae0f3..4c30153 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 every resource of a type, or fetch a single one by name. -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]({{< 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 b4d4ecf..fee21b1 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 an agent project with YAML and framework stubs." --- -Scaffold a new agent project. + -Picks a framework and language interactively (or via `--framework` / `--language`). Writes: -- `agent.yaml` — `v1alpha1` envelope +Scaffold a new agent project with declarative YAML and framework stubs. + +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]({{< 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 0f3eb0f..e133c50 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 an MCP server project with 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 with declarative YAML and framework stubs. -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]({{< 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 56cf22d..916a55c 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 declarative prompt YAML (ar.dev/v1alpha1)." --- -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]({{< 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 8a2d4aa..2f12a9c 100644 --- a/content/docs/reference/cli/arctl-init-skill.md +++ b/content/docs/reference/cli/arctl-init-skill.md @@ -1,12 +1,17 @@ --- title: arctl init skill -description: "Scaffold a new skill project with declarative YAML and source stubs." weight: 10 +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: + ```sh arctl apply -f NAME/skill.yaml ``` @@ -18,6 +23,7 @@ arctl init skill NAME [flags] ``` Examples: + ```sh arctl init skill my-skill arctl init skill my-skill --description "Text summarizer" @@ -32,6 +38,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]({{< 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 df79af7..aac3ab0 100644 --- a/content/docs/reference/cli/arctl-init.md +++ b/content/docs/reference/cli/arctl-init.md @@ -1,26 +1,33 @@ --- title: arctl init -description: "Scaffold a new declarative resource project (agent, MCP server, skill, or prompt)." weight: 10 +description: "Scaffold a declarative agent, MCP, skill, or prompt project." --- -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 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: -- `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 +35,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]({{< 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 69060be..dd22c2d 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 repo 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]({{< 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 4ab70d9..5878d25 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 in the current project directory." --- -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. +Run the agent or MCP server defined by the declarative YAML in the +project directory (defaults to "."). -**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 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 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. +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. + +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]({{< 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 48d2ccb..8e1f606 100644 --- a/content/docs/reference/cli/arctl-version.md +++ b/content/docs/reference/cli/arctl-version.md @@ -1,10 +1,13 @@ --- title: arctl version -description: "Display the version of the arctl CLI." weight: 10 +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 @@ -12,12 +15,6 @@ Displays the version of `arctl`. arctl version [flags] ``` -Examples: -```sh -arctl version -arctl version --json -``` - ## Command-specific flags ```sh @@ -31,3 +28,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]({{< 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 c29d0fb..3b8530d 100644 --- a/content/docs/reference/cli/arctl-wait.md +++ b/content/docs/reference/cli/arctl-wait.md @@ -1,21 +1,29 @@ --- 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. + + +Wait for a registry resource to reach a target state, polling until it +gets there or the timeout expires. -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 +32,7 @@ arctl wait TYPE NAME [flags] ``` Examples: + ```sh arctl wait deployment aws-v1 arctl wait deployment team-a/aws-v1 @@ -45,3 +54,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]({{< 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 new file mode 100644 index 0000000..dd13914 --- /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]({{< 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/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/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..dcf7711 100644 --- a/hugo_stats.json +++ b/hugo_stats.json @@ -4,7 +4,6 @@ "a", "article", "aside", - "blockquote", "body", "br", "button", @@ -105,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", @@ -155,7 +155,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", @@ -457,7 +456,9 @@ "nav-link", "nav-link-kbd", "nav-links", + "openapi-container", "page-description", + "pnf-code", "preview-appbar", "preview-appbar-brand", "preview-appbar-right", @@ -498,8 +499,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 +541,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 +570,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 +581,6 @@ "faqs", "favicon-svg", "features", - "fish", - "from-the-registry", "gateway", "get-started", "global-flags", @@ -607,8 +597,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 +618,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,25 +630,21 @@ "step-1-install-kagent", "step-2-configure-agentregistry", "step-2-verify-the-runtime", - "sub-commands", "supported-clients", "supported-tools", + "swagger-ui", "tabs-panel-tabs-00-0", "tabs-panel-tabs-00-1", "tabs-panel-tabs-01-0", "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 +653,7 @@ "updates-and-questions", "usage", "verify-the-agent", - "verify-the-deployment", - "zsh" + "verify-the-deployment" ] } } 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-arctl-ref.py b/scripts/generate-arctl-ref.py new file mode 100644 index 0000000..134fb06 --- /dev/null +++ b/scripts/generate-arctl-ref.py @@ -0,0 +1,647 @@ +#!/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" + +# 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. +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: + """Rewrite cobra's relative .md cross-links as `link-hextra` calls. + + 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 + [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: + 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. + + 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. + 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), + )) + + # 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()) + + # 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 += "." + + 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() 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" . }}