From b4e0dffc12fca416d3241d3999188fc02fb7a940 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Mon, 30 Mar 2026 15:29:04 +0000 Subject: [PATCH] Update ToolHive reference docs for v0.14.1 --- docs/toolhive/reference/cli/thv.md | 1 + docs/toolhive/reference/cli/thv_skill.md | 42 +++++++++++++++++ .../toolhive/reference/cli/thv_skill_build.md | 42 +++++++++++++++++ docs/toolhive/reference/cli/thv_skill_info.md | 42 +++++++++++++++++ .../reference/cli/thv_skill_install.md | 45 +++++++++++++++++++ docs/toolhive/reference/cli/thv_skill_list.md | 44 ++++++++++++++++++ docs/toolhive/reference/cli/thv_skill_push.md | 39 ++++++++++++++++ .../reference/cli/thv_skill_uninstall.md | 41 +++++++++++++++++ .../reference/cli/thv_skill_validate.md | 40 +++++++++++++++++ docs/toolhive/reference/crd-spec.md | 24 +++++++++- 10 files changed, 359 insertions(+), 1 deletion(-) create mode 100644 docs/toolhive/reference/cli/thv_skill.md create mode 100644 docs/toolhive/reference/cli/thv_skill_build.md create mode 100644 docs/toolhive/reference/cli/thv_skill_info.md create mode 100644 docs/toolhive/reference/cli/thv_skill_install.md create mode 100644 docs/toolhive/reference/cli/thv_skill_list.md create mode 100644 docs/toolhive/reference/cli/thv_skill_push.md create mode 100644 docs/toolhive/reference/cli/thv_skill_uninstall.md create mode 100644 docs/toolhive/reference/cli/thv_skill_validate.md diff --git a/docs/toolhive/reference/cli/thv.md b/docs/toolhive/reference/cli/thv.md index dc043452..9f6b4ac6 100644 --- a/docs/toolhive/reference/cli/thv.md +++ b/docs/toolhive/reference/cli/thv.md @@ -52,6 +52,7 @@ thv [flags] * [thv search](thv_search.md) - Search for MCP servers * [thv secret](thv_secret.md) - Manage secrets * [thv serve](thv_serve.md) - Start the ToolHive API server +* [thv skill](thv_skill.md) - Manage skills * [thv start](thv_start.md) - Start (resume) a tooling server * [thv status](thv_status.md) - Show detailed status of an MCP server * [thv stop](thv_stop.md) - Stop one or more MCP servers diff --git a/docs/toolhive/reference/cli/thv_skill.md b/docs/toolhive/reference/cli/thv_skill.md new file mode 100644 index 00000000..0f6a3b1c --- /dev/null +++ b/docs/toolhive/reference/cli/thv_skill.md @@ -0,0 +1,42 @@ +--- +title: thv skill +hide_title: true +description: Reference for ToolHive CLI command `thv skill` +last_update: + author: autogenerated +slug: thv_skill +mdx: + format: md +--- + +## thv skill + +Manage skills + +### Synopsis + +The skill command provides subcommands to manage skills. + +### Options + +``` + -h, --help help for skill +``` + +### Options inherited from parent commands + +``` + --debug Enable debug mode +``` + +### SEE ALSO + +* [thv](thv.md) - ToolHive (thv) is a lightweight, secure, and fast manager for MCP servers +* [thv skill build](thv_skill_build.md) - Build a skill +* [thv skill info](thv_skill_info.md) - Show skill details +* [thv skill install](thv_skill_install.md) - Install a skill +* [thv skill list](thv_skill_list.md) - List installed skills +* [thv skill push](thv_skill_push.md) - Push a built skill +* [thv skill uninstall](thv_skill_uninstall.md) - Uninstall a skill +* [thv skill validate](thv_skill_validate.md) - Validate a skill definition + diff --git a/docs/toolhive/reference/cli/thv_skill_build.md b/docs/toolhive/reference/cli/thv_skill_build.md new file mode 100644 index 00000000..8ca6fe3d --- /dev/null +++ b/docs/toolhive/reference/cli/thv_skill_build.md @@ -0,0 +1,42 @@ +--- +title: thv skill build +hide_title: true +description: Reference for ToolHive CLI command `thv skill build` +last_update: + author: autogenerated +slug: thv_skill_build +mdx: + format: md +--- + +## thv skill build + +Build a skill + +### Synopsis + +Build a skill from a local directory into an OCI artifact that can be pushed to a registry. + +On success, prints the OCI reference of the built artifact to stdout. + +``` +thv skill build [path] [flags] +``` + +### Options + +``` + -h, --help help for build + -t, --tag string OCI tag for the built artifact +``` + +### Options inherited from parent commands + +``` + --debug Enable debug mode +``` + +### SEE ALSO + +* [thv skill](thv_skill.md) - Manage skills + diff --git a/docs/toolhive/reference/cli/thv_skill_info.md b/docs/toolhive/reference/cli/thv_skill_info.md new file mode 100644 index 00000000..990a81b6 --- /dev/null +++ b/docs/toolhive/reference/cli/thv_skill_info.md @@ -0,0 +1,42 @@ +--- +title: thv skill info +hide_title: true +description: Reference for ToolHive CLI command `thv skill info` +last_update: + author: autogenerated +slug: thv_skill_info +mdx: + format: md +--- + +## thv skill info + +Show skill details + +### Synopsis + +Display detailed information about a skill, including metadata, version, and installation status. + +``` +thv skill info [skill-name] [flags] +``` + +### Options + +``` + --format string Output format (json, text) (default "text") + -h, --help help for info + --project-root string Project root path for project-scoped skills + --scope string Filter by scope (user, project) +``` + +### Options inherited from parent commands + +``` + --debug Enable debug mode +``` + +### SEE ALSO + +* [thv skill](thv_skill.md) - Manage skills + diff --git a/docs/toolhive/reference/cli/thv_skill_install.md b/docs/toolhive/reference/cli/thv_skill_install.md new file mode 100644 index 00000000..d8e8703a --- /dev/null +++ b/docs/toolhive/reference/cli/thv_skill_install.md @@ -0,0 +1,45 @@ +--- +title: thv skill install +hide_title: true +description: Reference for ToolHive CLI command `thv skill install` +last_update: + author: autogenerated +slug: thv_skill_install +mdx: + format: md +--- + +## thv skill install + +Install a skill + +### Synopsis + +Install a skill by name or OCI reference. +The skill will be fetched from a remote registry and installed locally. + +``` +thv skill install [skill-name] [flags] +``` + +### Options + +``` + --client string Target client application (e.g. claude-code) + --force Overwrite existing skill directory + --group string Group to add the skill to after installation + -h, --help help for install + --project-root string Project root path for project-scoped installs + --scope string Installation scope (user, project) (default "user") +``` + +### Options inherited from parent commands + +``` + --debug Enable debug mode +``` + +### SEE ALSO + +* [thv skill](thv_skill.md) - Manage skills + diff --git a/docs/toolhive/reference/cli/thv_skill_list.md b/docs/toolhive/reference/cli/thv_skill_list.md new file mode 100644 index 00000000..118a9dde --- /dev/null +++ b/docs/toolhive/reference/cli/thv_skill_list.md @@ -0,0 +1,44 @@ +--- +title: thv skill list +hide_title: true +description: Reference for ToolHive CLI command `thv skill list` +last_update: + author: autogenerated +slug: thv_skill_list +mdx: + format: md +--- + +## thv skill list + +List installed skills + +### Synopsis + +List all currently installed skills and their status. + +``` +thv skill list [flags] +``` + +### Options + +``` + --client string Filter by client application + --format string Output format (json, text) (default "text") + --group string Filter by group + -h, --help help for list + --project-root string Project root path for project-scoped skills + --scope string Filter by scope (user, project) +``` + +### Options inherited from parent commands + +``` + --debug Enable debug mode +``` + +### SEE ALSO + +* [thv skill](thv_skill.md) - Manage skills + diff --git a/docs/toolhive/reference/cli/thv_skill_push.md b/docs/toolhive/reference/cli/thv_skill_push.md new file mode 100644 index 00000000..b370b1b7 --- /dev/null +++ b/docs/toolhive/reference/cli/thv_skill_push.md @@ -0,0 +1,39 @@ +--- +title: thv skill push +hide_title: true +description: Reference for ToolHive CLI command `thv skill push` +last_update: + author: autogenerated +slug: thv_skill_push +mdx: + format: md +--- + +## thv skill push + +Push a built skill + +### Synopsis + +Push a previously built skill artifact to a remote OCI registry. + +``` +thv skill push [reference] [flags] +``` + +### Options + +``` + -h, --help help for push +``` + +### Options inherited from parent commands + +``` + --debug Enable debug mode +``` + +### SEE ALSO + +* [thv skill](thv_skill.md) - Manage skills + diff --git a/docs/toolhive/reference/cli/thv_skill_uninstall.md b/docs/toolhive/reference/cli/thv_skill_uninstall.md new file mode 100644 index 00000000..7dabfd28 --- /dev/null +++ b/docs/toolhive/reference/cli/thv_skill_uninstall.md @@ -0,0 +1,41 @@ +--- +title: thv skill uninstall +hide_title: true +description: Reference for ToolHive CLI command `thv skill uninstall` +last_update: + author: autogenerated +slug: thv_skill_uninstall +mdx: + format: md +--- + +## thv skill uninstall + +Uninstall a skill + +### Synopsis + +Remove a previously installed skill by name. + +``` +thv skill uninstall [skill-name] [flags] +``` + +### Options + +``` + -h, --help help for uninstall + --project-root string Project root path for project-scoped skills + --scope string Scope to uninstall from (user, project) (default "user") +``` + +### Options inherited from parent commands + +``` + --debug Enable debug mode +``` + +### SEE ALSO + +* [thv skill](thv_skill.md) - Manage skills + diff --git a/docs/toolhive/reference/cli/thv_skill_validate.md b/docs/toolhive/reference/cli/thv_skill_validate.md new file mode 100644 index 00000000..0a7cc772 --- /dev/null +++ b/docs/toolhive/reference/cli/thv_skill_validate.md @@ -0,0 +1,40 @@ +--- +title: thv skill validate +hide_title: true +description: Reference for ToolHive CLI command `thv skill validate` +last_update: + author: autogenerated +slug: thv_skill_validate +mdx: + format: md +--- + +## thv skill validate + +Validate a skill definition + +### Synopsis + +Check that a skill definition in the given directory is valid and well-formed. + +``` +thv skill validate [path] [flags] +``` + +### Options + +``` + --format string Output format (json, text) (default "text") + -h, --help help for validate +``` + +### Options inherited from parent commands + +``` + --debug Enable debug mode +``` + +### SEE ALSO + +* [thv skill](thv_skill.md) - Manage skills + diff --git a/docs/toolhive/reference/crd-spec.md b/docs/toolhive/reference/crd-spec.md index 386a9899..9b4b0b29 100644 --- a/docs/toolhive/reference/crd-spec.md +++ b/docs/toolhive/reference/crd-spec.md @@ -124,6 +124,7 @@ _Appears in:_ | `audience` _string_ | Audience is the target audience for the exchanged token. | | | | `scopes` _string array_ | Scopes are the requested scopes for the exchanged token. | | | | `subjectTokenType` _string_ | SubjectTokenType is the token type of the incoming subject token.
Defaults to "urn:ietf:params:oauth:token-type:access_token" if not specified. | | | +| `subjectProviderName` _string_ | SubjectProviderName selects which upstream provider's token to use as the
subject token. When set, the token is looked up from Identity.UpstreamTokens
instead of using Identity.Token. | | | #### auth.types.UpstreamInjectConfig @@ -1242,6 +1243,7 @@ _Appears in:_ | `unauthenticated` | ExternalAuthTypeUnauthenticated is the type for no authentication
This should only be used for backends on trusted networks (e.g., localhost, VPC)
or when authentication is handled by network-level security
| | `embeddedAuthServer` | ExternalAuthTypeEmbeddedAuthServer is the type for embedded OAuth2/OIDC authorization server
This enables running an embedded auth server that delegates to upstream IDPs
| | `awsSts` | ExternalAuthTypeAWSSts is the type for AWS STS authentication
| +| `upstreamInject` | ExternalAuthTypeUpstreamInject is the type for upstream token injection
This injects an upstream IDP access token as the Authorization: Bearer header
| #### api.v1alpha1.GitAuthConfig @@ -1484,12 +1486,13 @@ _Appears in:_ | Field | Description | Default | Validation | | --- | --- | --- | --- | -| `type` _[api.v1alpha1.ExternalAuthType](#apiv1alpha1externalauthtype)_ | Type is the type of external authentication to configure | | Enum: [tokenExchange headerInjection bearerToken unauthenticated embeddedAuthServer awsSts]
Required: \{\}
| +| `type` _[api.v1alpha1.ExternalAuthType](#apiv1alpha1externalauthtype)_ | Type is the type of external authentication to configure | | Enum: [tokenExchange headerInjection bearerToken unauthenticated embeddedAuthServer awsSts upstreamInject]
Required: \{\}
| | `tokenExchange` _[api.v1alpha1.TokenExchangeConfig](#apiv1alpha1tokenexchangeconfig)_ | TokenExchange configures RFC-8693 OAuth 2.0 Token Exchange
Only used when Type is "tokenExchange" | | Optional: \{\}
| | `headerInjection` _[api.v1alpha1.HeaderInjectionConfig](#apiv1alpha1headerinjectionconfig)_ | HeaderInjection configures custom HTTP header injection
Only used when Type is "headerInjection" | | Optional: \{\}
| | `bearerToken` _[api.v1alpha1.BearerTokenConfig](#apiv1alpha1bearertokenconfig)_ | BearerToken configures bearer token authentication
Only used when Type is "bearerToken" | | Optional: \{\}
| | `embeddedAuthServer` _[api.v1alpha1.EmbeddedAuthServerConfig](#apiv1alpha1embeddedauthserverconfig)_ | EmbeddedAuthServer configures an embedded OAuth2/OIDC authorization server
Only used when Type is "embeddedAuthServer" | | Optional: \{\}
| | `awsSts` _[api.v1alpha1.AWSStsConfig](#apiv1alpha1awsstsconfig)_ | AWSSts configures AWS STS authentication with SigV4 request signing
Only used when Type is "awsSts" | | Optional: \{\}
| +| `upstreamInject` _[api.v1alpha1.UpstreamInjectSpec](#apiv1alpha1upstreaminjectspec)_ | UpstreamInject configures upstream token injection for backend requests.
Only used when Type is "upstreamInject". | | Optional: \{\}
| #### api.v1alpha1.MCPExternalAuthConfigStatus @@ -2874,6 +2877,7 @@ _Appears in:_ | `scopes` _string array_ | Scopes is a list of OAuth 2.0 scopes to request for the exchanged token | | Optional: \{\}
| | `subjectTokenType` _string_ | SubjectTokenType is the type of the incoming subject token.
Accepts short forms: "access_token" (default), "id_token", "jwt"
Or full URNs: "urn:ietf:params:oauth:token-type:access_token",
"urn:ietf:params:oauth:token-type:id_token",
"urn:ietf:params:oauth:token-type:jwt"
For Google Workload Identity Federation with OIDC providers (like Okta), use "id_token" | | Pattern: `^(access_token\|id_token\|jwt\|urn:ietf:params:oauth:token-type:(access_token\|id_token\|jwt))?$`
Optional: \{\}
| | `externalTokenHeaderName` _string_ | ExternalTokenHeaderName is the name of the custom header to use for the exchanged token.
If set, the exchanged token will be added to this custom header (e.g., "X-Upstream-Token").
If empty or not set, the exchanged token will replace the Authorization header (default behavior). | | Optional: \{\}
| +| `subjectProviderName` _string_ | SubjectProviderName is the name of the upstream provider whose token is used as the
RFC 8693 subject token instead of identity.Token when performing token exchange. | | Optional: \{\}
| #### api.v1alpha1.TokenLifespanConfig @@ -2975,6 +2979,24 @@ _Appears in:_ | `annotations` _[api.v1alpha1.ToolAnnotationsOverride](#apiv1alpha1toolannotationsoverride)_ | Annotations overrides specific tool annotation fields.
Only specified fields are overridden; others pass through from the backend. | | Optional: \{\}
| +#### api.v1alpha1.UpstreamInjectSpec + + + +UpstreamInjectSpec holds configuration for upstream token injection. +This strategy injects an upstream IDP access token obtained by the embedded +authorization server into backend requests as the Authorization: Bearer header. + + + +_Appears in:_ +- [api.v1alpha1.MCPExternalAuthConfigSpec](#apiv1alpha1mcpexternalauthconfigspec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `providerName` _string_ | ProviderName is the name of the upstream IDP provider whose access token
should be injected as the Authorization: Bearer header. | | MinLength: 1
Required: \{\}
| + + #### api.v1alpha1.UpstreamProviderConfig