diff --git a/assets/ar-docs/setup-docker.md b/assets/ar-docs/setup-docker.md new file mode 100644 index 0000000..f3090c9 --- /dev/null +++ b/assets/ar-docs/setup-docker.md @@ -0,0 +1,36 @@ +1. Install the agentregistry `arctl` binary on your local machine. + ```sh + curl -fsSL https://raw.githubusercontent.com/agentregistry-dev/agentregistry/main/scripts/get-arctl | bash + + export PATH="/usr/local/bin:$PATH" + ``` + +2. Verify that the CLI is installed correctly. + ```sh + arctl version + ``` + +3. Download the Docker Compose file that matches your installed `arctl` version. + ```sh + export VERSION="$(arctl version | awk 'NR == 1 { print $3 }')" + curl -fsSLo agentregistry-compose.yml \ + "https://raw.githubusercontent.com/agentregistry-dev/agentregistry/${VERSION}/docker/docker-compose.yml" + ``` + +4. Start the agentregistry server and its bundled PostgreSQL database. + ```sh + docker compose -f agentregistry-compose.yml up -d --wait + ``` + + Example output: + ```console + [+] Running 4/4 + ✔ Network agentregistry_agentregistry-network Created 0.0s + ✔ Volume agentregistry_postgres_data Created 0.0s + ✔ Container agent-registry-postgres Healthy 6.3s + ✔ Container agentregistry-server Healthy + ``` + +5. [Open the agentregistry UI](http://localhost:12121/) in your browser. The UI is automatically exposed on port 12121 on your local machine. + + {{< reuse-image src="img/ar-local.svg" width="800px" srcDark="img/ar-local-dark.svg" >}} \ No newline at end of file diff --git a/assets/img/ar-local-dark.svg b/assets/img/ar-local-dark.svg new file mode 100644 index 0000000..be566b2 --- /dev/null +++ b/assets/img/ar-local-dark.svg @@ -0,0 +1,4 @@ + + + \ No newline at end of file diff --git a/assets/img/ar-local.svg b/assets/img/ar-local.svg new file mode 100644 index 0000000..9475048 --- /dev/null +++ b/assets/img/ar-local.svg @@ -0,0 +1,4 @@ + + + \ No newline at end of file diff --git a/content/docs/install/docker.md b/content/docs/install/docker.md index f7e997c..31af808 100644 --- a/content/docs/install/docker.md +++ b/content/docs/install/docker.md @@ -6,7 +6,7 @@ description: "Install agentregistry for local development with Docker to build, Use this guide to install agentregistry for local development with Docker. This approach is useful if you want to run agentregistry from your local machine, an on-prem environment, or a VM. Agentregistry is spun up using Docker containers and you can use this installation to build, publish, and deploy AI artifacts to your local environment and Kubernetes clusters. -To install agentregistry in a Kubernetes cluster instead, see the [Install in Kubernetes](/docs/install/kubernetes) guide. +To install agentregistry in a Kubernetes cluster instead, see the [Install in Kubernetes](/docs/install/kubernetes/) guide. ## Before you begin @@ -18,41 +18,7 @@ To install agentregistry in a Kubernetes cluster instead, see the [Install in Ku ## Install -1. Install the `arctl` binary on your local machine. The binary is automatically added to `/usr/local/bin/arctl`. - ```sh - curl -fsSL https://raw.githubusercontent.com/agentregistry-dev/agentregistry/main/scripts/get-arctl | bash - ``` - -2. Start the agentregistry daemon. This starts the Docker containers that power agentregistry. - ```sh - arctl daemon start - ``` - - Example output: - ```console - Starting agentregistry daemon... - ✓ agentregistry daemon started successfully - ``` - -3. Verify the installation by checking the version. - ```sh - arctl version - ``` - - Example output: - ```console - arctl version v0.3.3 - Git commit: 89dc215 - Build date: 2026-04-02 - Server version: v0.3.3 - Server git commit: 89dc215 - Server build date: 2026-04-02 - ``` - -4. [Open the agentregistry UI](http://localhost:12121/) in your browser. The UI is automatically exposed on port `12121` when the daemon starts. - - {{< reuse-image src="img/ar-local.png" width="800px" >}} - {{< reuse-image-dark srcDark="img/ar-local-dark.png" width="800px" >}} +{{< reuse "ar-docs/setup-docker.md" >}} ## Next steps @@ -62,3 +28,4 @@ With agentregistry up and running, you can explore how to build, publish, and de * [**MCP servers**](/docs/mcp/): Create and run MCP tool servers, add tools, and publish them as Docker images. * [**Skills**](/docs/skills/): Build and publish skills that you can add to your agents. * [**Prompts**](/docs/prompts/): Build and publish prompts that you can add to your agents. +* [**BYO PostgreSQL database**]({{< link path="/operations/database/" >}}): Replace the bundled PostgreSQL instance with an external database for production use. diff --git a/content/docs/install/kubernetes.md b/content/docs/install/kubernetes.md index 7f24758..992ceab 100644 --- a/content/docs/install/kubernetes.md +++ b/content/docs/install/kubernetes.md @@ -1,5 +1,5 @@ --- -title: Install in Kubernetes +title: Install on Kubernetes weight: 20 description: "Install agentregistry in a Kubernetes cluster with Helm for shared team access to a central artifact registry." --- @@ -7,7 +7,7 @@ description: "Install agentregistry in a Kubernetes cluster with Helm for shared Use this guide to install agentregistry in a Kubernetes cluster by using Helm. This approach is useful for team environments where multiple developers need shared access to a central artifact registry. > [!NOTE] -> If you install agentregistry in a Kubernetes cluster, you cannot deploy AI artifacts to a local environment. To deploy them to a local environment, you must [install agentregistry locally with Docker](/docs/install/docker). +> If you install agentregistry in a Kubernetes cluster, you cannot deploy AI artifacts to a local environment. To deploy them to a local environment, you must [install agentregistry locally with Docker](/docs/install/docker/). ## Before you begin @@ -16,67 +16,55 @@ Make sure you have the following tools installed: - [kubectl](https://kubernetes.io/docs/tasks/tools/) with access to a Kubernetes cluster - [Helm](https://helm.sh/docs/intro/install/) v3 or later -## Set up PostgreSQL - -Agentregistry requires an external PostgreSQL instance with the [pgvector](https://github.com/pgvector/pgvector) extension for Kubernetes deployments. - -> [!WARNING] -> The bundled PostgreSQL setup is intended for development and testing only. For production, use a managed PostgreSQL service or a production-grade operator. - ## Install with Helm -Install agentregistry using the Helm chart from the GitHub Container Registry. - -```sh -helm upgrade -i agentregistry oci://ghcr.io/agentregistry-dev/agentregistry/charts/agentregistry \ - --namespace agentregistry \ - --create-namespace \ - --set config.jwtPrivateKey=$(openssl rand -hex 32) \ - --set image.tag=v0.3.3 \ - --set database.host=postgres-pgvector.agentregistry.svc.cluster.local \ - --set database.password=agentregistry \ - --set database.sslMode=disable -``` +The Helm chart includes a bundled PostgreSQL instance for development and evaluation. For production, [bring your own PostgreSQL instance]({{< link path="/operations/database/" >}}) instead. -If you are using an external PostgreSQL instance, replace `database.host`, `database.password`, and `database.sslMode` with values for your database. - -Verify that the pods are running. - -```sh -kubectl get pods -n agentregistry -``` +1. Install agentregistry with the bundled PostgreSQL instance. + ```sh + helm upgrade -i agentregistry oci://ghcr.io/agentregistry-dev/agentregistry/charts/agentregistry \ + --namespace agentregistry \ + --create-namespace + ``` -### Helm chart configuration + > [!WARNING] + > The bundled PostgreSQL instance is for development and evaluation only. Data is lost if the PostgreSQL pod is restarted or rescheduled. For production, use an external PostgreSQL instance instead. See the [BYO PostgreSQL database]({{< link path="/operations/database/" >}}) guide. -| Value | Description | Default | -|---|---|---| -| `database.host` | PostgreSQL hostname | — | -| `database.password` | Database password | — | -| `database.sslMode` | SSL mode (`disable`, `require`, `verify-full`) | — | -| `config.jwtPrivateKey` | JWT signing key (use a securely generated random value) | — | +2. Verify that the agentregistry and PostgreSQL pods are up and running. + ```sh + kubectl get pods -n agentregistry + ``` -## Access the UI + Example output: + ```console + NAME READY STATUS RESTARTS AGE + agentregistry-c46b8bd98-hvnzf 1/1 Running 0 45s + gentregistry-postgresql-9858cbcbf-tk7p9 1/1 Running 0 45s + ``` -1. Port-forward the agentregistry service to access the UI and API from your local machine: +3. Port-forward the agentregistry service to access the UI and API from your local machine. ```sh kubectl port-forward -n agentregistry svc/agentregistry 12121:12121 ``` -2. [Open the agentregistry UI](http://localhost:12121/) in your browser. +4. [Open the agentregistry UI](http://localhost:12121/) in your browser. -## Install arctl +### Install the `arctl` CLI -Install the `arctl` CLI to interact with agentregistry from your local machine: +1. Install the agentregistry `arctl` binary on your local machine. + ```sh + curl -fsSL https://raw.githubusercontent.com/agentregistry-dev/agentregistry/main/scripts/get-arctl | bash -```sh -curl -fsSL https://raw.githubusercontent.com/agentregistry-dev/agentregistry/main/scripts/get-arctl | bash -``` + export PATH="/usr/local/bin:$PATH" + ``` -By default, `arctl` connects to `http://localhost:12121`. If your agentregistry instance is exposed at a different address, configure the connection: +2. Verify that the CLI is installed correctly. + ```sh + arctl version + ``` -```sh -arctl configure --url http://:12121 -``` +> [!TIP] +> By default, `arctl` connects to `http://localhost:12121`. If your agentregistry instance is exposed at a different address, set the `ARCTL_API_BASE_URL` environment variable or pass `--registry-url` on each command. For example, to set the environment variable, use `export ARCTL_API_BASE_URL=http://:12121`. ## Next steps diff --git a/content/docs/operations/_index.md b/content/docs/operations/_index.md new file mode 100644 index 0000000..67080d2 --- /dev/null +++ b/content/docs/operations/_index.md @@ -0,0 +1,5 @@ +--- +title: Operations +weight: 90 +description: "Operational guides for running agentregistry in production." +--- diff --git a/content/docs/operations/database.md b/content/docs/operations/database.md new file mode 100644 index 0000000..a9ec132 --- /dev/null +++ b/content/docs/operations/database.md @@ -0,0 +1,253 @@ +--- +title: BYO PostgreSQL database +weight: 10 +description: "Replace the built-in PostgreSQL database with an external instance for production use." +--- + +By default, agentregistry deploys a bundled PostgreSQL database that stores the AI artifacts you publish in the registry catalog. Because it runs as a single pod, data is lost when the pod restarts or becomes unavailable. + +For production environments, replace the bundled database with an external PostgreSQL instance that you manage and back up independently. + +## Before you begin + +- Creata or use an existing external PostgreSQL instance (version 14 or later) that is reachable from your agentregistry installation. For example, you can create an [Amazon RDS instance](https://aws.amazon.com/rds/resources/) +- Install agentregistry on [Docker]({{< link path="/install/docker" >}}) or [Kubernetes]({{< link path="/install/kubernetes" >}}) guide. + +## Step 1: Create the agentregistry database + +1. Get the address of your PostgreSQL instance, and the admin's user name and password. Store these details in environment variables. + ```sh + export PG_HOST= + export PG_USER= + export PG_PASS= + ``` + +2. Create the `agentregistry` database. + ```sh + psql "host=$PG_HOST port=5432 user=$PG_USER password='$PG_PASS' dbname=postgres sslmode=require" \ + -c 'CREATE DATABASE agentregistry;' + ``` + + Example output: + ```console + CREATE DATABASE + ``` + +## Step 2: Configure agentregistry + +Configure agentregistry to use your external PostgreSQL instance. The setup varies depending on how you installed agentregistry on [Docker](#docker) or [Kubernetes](#kubernetes). + +### Docker + +1. Open `agentregistry-compose.yml` file. + ```sh + nano agentregistry-compose.yml + ``` + +2. Make the following changes. + 1. Remove the `postgres` service block entirely. + 2. Remove the `postgres_data` volume. + 3. Update the `AGENT_REGISTRY_DATABASE_URL` in the `agentregistry` service to point at your external database. + 4. Remove the `depends_on` condition that references the bundled postgres service. + + The updated `agentregistry` service looks similar to the following: + + ```yaml + services: + agentregistry: + image: ghcr.io/agentregistry-dev/agentregistry/server:${VERSION} + container_name: agentregistry-server + entrypoint: + - /bin/sh + - -c + - | + if [ -f /root/.kube/config.orig ]; then + mkdir -p /root/.kube + sed -E \ + -e 's|https://127\.0\.0\.1|https://host.docker.internal|g' \ + -e 's|https://localhost|https://host.docker.internal|g' \ + -e 's|certificate-authority-data:.*|insecure-skip-tls-verify: true|g' \ + /root/.kube/config.orig > /root/.kube/config + fi + exec /app/bin/arctl-server + environment: + AGENT_REGISTRY_DATABASE_URL: "postgres://user:password@your-pg-host:5432/agentregistry?sslmode=require" + AGENT_REGISTRY_SERVER_ADDRESS: ":8080" + AGENT_REGISTRY_ENABLE_REGISTRY_VALIDATION: "false" + AGENT_REGISTRY_MCP_PORT: "31313" + KUBECONFIG: "/root/.kube/config" + ports: + - "12121:8080" + - "31313:31313" + ... + ``` + +3. Restart agentregistry. + ```sh + docker compose -f agentregistry-compose.yml down + docker compose -f agentregistry-compose.yml up -d --wait + ``` + +4. Check the server logs for successful migration messages. + ```sh + docker compose -f agentregistry-compose.yml logs agentregistry | grep "migration" + ``` + + Example output: + ```console + {"time":"...","level":"info","msg":"all migrations applied successfully","component":"database.migrate"} + ``` + +### Kubernetes + +1. Store the database connection string in a Kubernetes Secret. The registry server reads the connection string from this Secret at startup. + + The connection string can be provided in two formats: + - **URL format**: `postgres://user:password@host:5432/agentregistry?sslmode=require` + Special characters in the password (such as `@`, `$`, `/`) must be percent-encoded. + - **DSN format**: `host=myhost port=5432 user=myuser password='mypass' dbname=agentregistry sslmode=require` + Wrap values that contain spaces or special characters in single quotes. No percent-encoding needed. + + > [!NOTE] + > If you plan to provide the connection string inline with the `--set` flag in the Helm upgrade, skip this step and continue with the next step. + + {{< tabs >}} + {{% tab name="URL format" %}} + + 1. Percent-encode special characters in your password. + ```sh + ENCODED_PASSWORD=$(python3 -c \ + "import urllib.parse, sys; print(urllib.parse.quote(sys.argv[1], safe=''))" \ + "$PG_PASS") + echo "Encoded password: $ENCODED_PASSWORD" + ``` + +2. Build the connection string. + ```sh + URL="postgres://${PG_USER}:${ENCODED_PASSWORD}@${PG_HOST}:${PG_PORT}/agentregistry?sslmode=require" + echo "Connection string: $URL" + ``` + +3. Create the Secret. + ```sh + kubectl -n agentregistry create secret generic agentregistry-db-creds \ + --from-literal=AGENT_REGISTRY_DATABASE_URL="$URL" + ``` + +4. Verify the Secret. + ```sh + kubectl -n agentregistry get secret agentregistry-db-creds \ + -o jsonpath="{.data.AGENT_REGISTRY_DATABASE_URL}" | base64 -d; echo + ``` + + {{% /tab %}} + {{% tab name="DSN format" %}} + +1. Build the connection string. + ```sh + DSN="host=$PG_HOST port=$PG_PORT user=$PG_USER password='$PG_PASS' dbname=agentregistry sslmode=require" + echo "Connection string: $DSN" + ``` + +2. Create the Secret. + ```sh + kubectl -n agentregistry create secret generic agentregistry-db-creds \ + --from-literal=AGENT_REGISTRY_DATABASE_URL="$DSN" + ``` + +3. Verify the Secret. + ```sh + kubectl -n agentregistry get secret agentregistry-db-creds \ + -o jsonpath="{.data.AGENT_REGISTRY_DATABASE_URL}" | base64 -d; echo + ``` + + {{% /tab %}} + {{< /tabs >}} + +2. Upgrade the Helm release to switch from the bundled PostgreSQL to your external instance. The `--reuse-values` flag re-applies all previous values so you only need to pass the database settings that are changing. + + {{< tabs >}} + {{% tab name="Kubernetes Secret" %}} + + ```sh + helm upgrade -i agentregistry \ + oci://ghcr.io/agentregistry-dev/agentregistry/charts/agentregistry \ + --namespace agentregistry \ + --reuse-values \ + --set database.postgres.type=external \ + --set database.postgres.external.secretRef.name=agentregistry-db-creds \ + --set database.postgres.external.secretRef.key=AGENT_REGISTRY_DATABASE_URL \ + --wait --timeout=5m + ``` + + {{% /tab %}} + {{% tab name="Inline connection string" %}} + + ```sh + helm upgrade -i agentregistry \ + oci://ghcr.io/agentregistry-dev/agentregistry/charts/agentregistry \ + --namespace agentregistry \ + --reuse-values \ + --set database.postgres.type=external \ + --set "database.postgres.external.url=${DSN}" \ + --wait --timeout=5m + ``` + + {{% /tab %}} + {{< /tabs >}} + + | Helm value | Description | + |---|---| + | `database.postgres.type` | Set to `external` to use your own database instead of the bundled instance. | + | `database.postgres.external.url` | Inline connection string. Mutually exclusive with `secretRef.name`. | + | `database.postgres.external.secretRef.name` | Name of a Kubernetes Secret holding the connection string. Mutually exclusive with `url`. | + | `database.postgres.external.secretRef.key` | Key within the Secret (default: `AGENT_REGISTRY_DATABASE_URL`). | + +3. Verify the pods are healthy and that no bundled `agentregistry-postgresql-*` pod is running. + ```sh + kubectl get pods -n agentregistry + ``` + +4. Confirm the server pod has the Secret reference in its environment. + ```sh + kubectl -n agentregistry describe pod -l app.kubernetes.io/component=server \ + | sed -n '/AGENT_REGISTRY_DATABASE_URL/,/^$/p' | head -5 + ``` + + Example output: + ```console + AGENT_REGISTRY_DATABASE_URL: Optional: false + ``` + +5. Check the server logs for successful migration messages. + ```sh + kubectl -n agentregistry logs deploy/agentregistry-server --tail=50 | grep "migration" + ``` + + Example output: + ```console + {"time":"...","level":"info","msg":"all migrations applied successfully","component":"database.migrate"} + ``` + +6. List the tables that the registry created on the database. + ```sh + psql "host=$PG_HOST port=$PG_PORT user=$PG_USER password='$PG_PASS' dbname=agentregistry sslmode=require" \ + -c '\dt' + ``` + + Example output: + ```console + List of relations + Schema | Name | Type | Owner + --------+----------------------+-------+----------- + public | agents | table | agentuser + public | control_plane_events | table | agentuser + public | deployments | table | agentuser + public | mcp_servers | table | agentuser + public | models | table | agentuser + public | plugins | table | agentuser + public | prompts | table | agentuser + public | runtimes | table | agentuser + public | skills | table | agentuser + (9 rows) + ``` diff --git a/content/docs/quickstart.md b/content/docs/quickstart.md index 75439a2..0db44ae 100644 --- a/content/docs/quickstart.md +++ b/content/docs/quickstart.md @@ -12,7 +12,7 @@ Want to learn more about agentregistry? Check out the [About](/docs/about/) sect In this guide, you learn how to install agentregistry for local development with Docker. This approach is useful if you want to run agentregistry from your local machine, an on-prem environment, or a VM. Agentregistry is spun up by using Docker containers and you can use this installation to deploy AI artifacts to your local environment and Kubernetes clusters. -To install agentregistry in a Kubernetes cluster instead, see the [Install in Kubernetes](/docs/install/kubernetes) guide. +To install agentregistry in a Kubernetes cluster instead, see the [Install in Kubernetes](/docs/install/kubernetes/) guide. ## Before you begin @@ -24,41 +24,7 @@ To install agentregistry in a Kubernetes cluster instead, see the [Install in Ku ## Setup -1. Install the agentregistry `arctl` binary on your local machine. The binary is automatically added to the `/usr/local/bin/arctl` directory. - ```sh - curl -fsSL https://raw.githubusercontent.com/agentregistry-dev/agentregistry/main/scripts/get-arctl | bash - ``` - -2. Start the agentregistry daemon. This starts the Docker containers that power agentregistry. - ```sh - arctl daemon start - ``` - - Example output: - ```console - Starting agentregistry daemon... - ✓ agentregistry daemon started successfully - ``` - -3. Verify the installation by checking the version. - ```sh - arctl version - ``` - - Example output: - ```console - arctl version v0.3.3 - Git commit: 89dc215 - Build date: 2026-04-02 - Server version: v0.3.3 - Server git commit: 89dc215 - Server build date: 2026-04-02 - ``` - -4. [Open the agentregistry UI](http://localhost:12121/) in your browser. The UI is automatically exposed on port 12121 on your local machine when you start the agentregistry daemon. - - {{< reuse-image src="img/ar-local.png" width="800px" >}} - {{< reuse-image-dark srcDark="img/ar-local-dark.png" width="800px" >}} +{{< reuse "ar-docs/setup-docker.md" >}} ## Next @@ -68,4 +34,6 @@ With agentregistry up and running, you can explore how to build, publish, and de * [**MCP servers**](/docs/mcp/): Create and run MCP tool servers, add tools, and publish them as Docker images in agentregistry. * [**Skills**](/docs/skills/): Build and publish skills that you can add to your agents. * [**Prompts**](/docs/prompts/): Build and publish prompts that you can add to your agents. - + +> [!TIP] +> To stop the registry while preserving its data, run `docker compose -f agentregistry-compose.yml down`. If you want to also remove the bundled PostgreSQL volume, add the `-v` flag. diff --git a/content/docs/reference/cli/arctl-agent-add-mcp.md b/content/docs/reference/cli/arctl-agent-add-mcp.md deleted file mode 100644 index 9440e2c..0000000 --- a/content/docs/reference/cli/arctl-agent-add-mcp.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: arctl agent add-mcp -description: "Add an MCP server entry to an agent's agent.yaml file." -weight: 10 ---- - -Add an MCP server entry to the `agent.yaml` file. Use flags for non-interactive setup or run without flags to open the wizard. - -## Usage - -```sh -arctl agent add-mcp [name] [args...] [flags] -``` - -Example: -```sh -arctl agent add-mcp my-mcp-server --command npx --arg "-y" --arg "mcp-server" -arctl agent add-mcp my-mcp-server --remote https://example.com/mcp -arctl agent add-mcp my-mcp-server --registry-server-name io.github.example/my-server --registry-server-version 1.0.0 -``` - -## Command-specific flags - -```sh ---arg strings: Command argument (repeatable) ---build string: Container build (optional; mutually exclusive with --image) ---command string: Command to run the MCP server (e.g., npx, uvx, arctl, or a binary) ---env strings: Environment variables in KEY=VALUE format (repeatable) ---header strings: HTTP header for remote MCP servers in KEY=VALUE format (repeatable, supports ${VAR} for env vars) ---image string: Container image (optional; mutually exclusive with --build) ---project-dir string: Project directory (default: current directory) (default ".") ---registry-server-name string: Registry-deployed MCP server name (optional; mutually exclusive with --remote, --command, --image, --build) ---registry-server-prefer-remote: Prefer remote MCP server (optional) ---registry-server-version string: Version of the MCP server to deploy from registry (e.g., 1.0.0) (optional) ---registry-url string: Registry URL (e.g., https://localhost:12121) (optional; mutually exclusive with --remote, --command, --image, --build) ---remote string: Remote MCP server URL (http/https) -``` - -## Global flags -```sh --v, --verbose: Enable verbose output. --h, --help: Display help information for the command. -``` \ No newline at end of file diff --git a/content/docs/reference/cli/arctl-agent-add-prompt.md b/content/docs/reference/cli/arctl-agent-add-prompt.md deleted file mode 100644 index a32f610..0000000 --- a/content/docs/reference/cli/arctl-agent-add-prompt.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: arctl agent add-prompt -description: "Add a prompt reference to an agent manifest." -weight: 10 ---- - -Add a prompt reference to the agent's `agent.yaml` file. The prompt is resolved from the registry when the agent runs. - -## Usage - -```sh -arctl agent add-prompt [flags] -``` - -Example: -```sh -arctl agent add-prompt reviewer --registry-prompt-name code-review -arctl agent add-prompt reviewer --registry-prompt-name code-review --registry-prompt-version 1.0.0 -arctl agent add-prompt reviewer --registry-prompt-name code-review --registry-url https://registry.example.com -``` - -## Command-specific flags - -```sh ---registry-prompt-name string: Prompt name in the registry (required) ---registry-prompt-version string: Version of the prompt to pull from the registry (optional; defaults to latest) ---registry-url string: Registry URL (default: current registry) ---project-dir string: Project directory (default: current directory) (default ".") -``` - -## Global flags -```sh --v, --verbose: Enable verbose output. --h, --help: Display help information for the command. -``` diff --git a/content/docs/reference/cli/arctl-agent-add-skill.md b/content/docs/reference/cli/arctl-agent-add-skill.md deleted file mode 100644 index 73c5d74..0000000 --- a/content/docs/reference/cli/arctl-agent-add-skill.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: arctl agent add-skill -description: "Add a skill to the agent manifest." -weight: 10 ---- - -Add a skill to the agent manifest. - -Skills can be added from the following sources: - -- A container image (via `--image`) -- An existing skill registry (via `--registry-skill-name`) - -When starting a new skill from scratch, use [`arctl skill init`](/docs/reference/cli/arctl-skill-init/) instead. - -## Usage - -```sh -arctl agent add-skill [flags] -``` - -Examples: -```sh -arctl agent add-skill my-skill --image docker.io/org/skill:latest -arctl agent add-skill my-skill --registry-skill-name cool-skill -``` - -## Command-specific flags - -```sh ---image string Docker image containing the skill ---project-dir string Project directory (default ".") ---registry-skill-name string Skill name in the registry ---registry-skill-version string Skill version to pull from the registry (defaults to latest) ---registry-url string Registry URL (defaults to the currently configured registry) -``` - -## Global flags -```sh --v, --verbose: Enable verbose output. --h, --help: Display help information for the command. -``` diff --git a/content/docs/reference/cli/arctl-agent-build.md b/content/docs/reference/cli/arctl-agent-build.md deleted file mode 100644 index a262881..0000000 --- a/content/docs/reference/cli/arctl-agent-build.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: arctl agent build -description: "Build Docker images for an agent project created with arctl agent init." -weight: 10 ---- - -Build Docker images for an agent project that you created with the `arctl agent init` command. - -This command looks for an `agent.yaml` file in the specified directory. It uses the file to generate template artifacts and to invoke the `docker build` command for both the agent and referenced MCP servers. You can optionally use the `--push` option to push the image to your container registry. - -## Usage - -```sh -arctl agent build [project-directory] [flags] -``` - -Example: -```sh -arctl agent build ./my-agent -arctl agent build ./my-agent --push --platform linux/amd64 -arctl agent build ./my-agent --image ghcr.io/myorg/my-agent:v1.0.0 -``` - -## Command-specific flags - -```sh ---image string: Full image specification (e.g., ghcr.io/myorg/my-agent:v1.0.0) ---platform string: Target platform for Docker build (e.g., linux/amd64, linux/arm64) ---push: Push the image to the registry -``` - -## Global flags -```sh --v, --verbose: Enable verbose output. --h, --help: Display help information for the command. -``` \ No newline at end of file diff --git a/content/docs/reference/cli/arctl-agent-delete.md b/content/docs/reference/cli/arctl-agent-delete.md deleted file mode 100644 index 13cf766..0000000 --- a/content/docs/reference/cli/arctl-agent-delete.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: arctl agent delete -description: "Delete an agent from the registry." -weight: 10 ---- - -Delete an agent from the registry. - -## Usage - -```sh -arctl agent delete [flags] -``` - -Example: -```sh -arctl agent delete my-agent --version 1.0.0 -``` - -## Command-specific flags - -```sh ---version string: Specify the version to delete (required) -``` - -## Global flags -```sh --v, --verbose: Enable verbose output. --h, --help: Display help information for the command. -``` \ No newline at end of file diff --git a/content/docs/reference/cli/arctl-agent-init.md b/content/docs/reference/cli/arctl-agent-init.md deleted file mode 100644 index f5679f6..0000000 --- a/content/docs/reference/cli/arctl-agent-init.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: arctl agent init -description: "Bootstrap a new agent project, specifying the ADK framework, language, and target directory." -weight: 10 ---- - -Bootstrap a new agent project. You must specify the ADK (Agent Development Kit) framework, the programming language, and the name of the directory you want to create. - -Supported frameworks and languages: -- `adk` (python) - -If no custom instruction file is provided, a default dice-rolling instruction will be used. -If no model flags are provided, defaults to Gemini (`gemini-2.0-flash`). - -## Usage - -```sh -arctl agent init [framework] [language] [agent-name] [flags] -``` - -Examples: -```sh -arctl agent init adk python dice -arctl agent init adk python dice --instruction-file instructions.md -arctl agent init adk python dice --model-provider Gemini --model-name gemini-2.0-flash -arctl agent init adk python dice --image ghcr.io/myorg/dice:v1.0 -``` - -## Command-specific flags - -```sh ---description string Description for the agent ---image string Docker image name including tag (e.g., ghcr.io/myorg/myagent:v1.0, docker.io/user/image:latest) ---instruction-file string Path to file containing custom instructions for the root agent ---model-name string Model name (e.g., gpt-4, claude-3-5-sonnet, gemini-2.0-flash) (default "gemini-2.0-flash") ---model-provider string Model provider (OpenAI, Anthropic, Gemini, AzureOpenAI, Agentgateway) (default "Gemini") ---telemetry string OTLP endpoint URL for OpenTelemetry traces (e.g., http://localhost:4318/v1/traces) -``` - -## Global flags -```sh --v, --verbose: Enable verbose output. --h, --help: Display help information for the command. -``` diff --git a/content/docs/reference/cli/arctl-agent-list.md b/content/docs/reference/cli/arctl-agent-list.md deleted file mode 100644 index 6e42948..0000000 --- a/content/docs/reference/cli/arctl-agent-list.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: arctl agent list -description: "List agents published to the registry." -weight: 10 ---- - -List agents that are published to the registry. - -## Usage - -```sh -arctl agent list [flags] -``` - -Example: -```sh -arctl agent list -arctl agent list --all --output json -``` - -## Command-specific flags - -```sh --a, --all: Show all items without pagination --o, --output string: Output format (table, json, yaml) (default "table") --p, --page-size int: Number of items per page (default 15) -``` - -## Global flags -```sh --v, --verbose: Enable verbose output. --h, --help: Display help information for the command. -``` \ No newline at end of file diff --git a/content/docs/reference/cli/arctl-agent-publish.md b/content/docs/reference/cli/arctl-agent-publish.md deleted file mode 100644 index 4c063c3..0000000 --- a/content/docs/reference/cli/arctl-agent-publish.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: arctl agent publish -description: "Publish an agent to the registry." -weight: 10 ---- - -Publish an agent to the registry. - -This command supports two modes: - -1. **From a local project directory** (with `agent.yaml`): Reads metadata from the local file and publishes the agent. -2. **Direct registration** (without `agent.yaml`): Registers an agent by name using `--git` and `--version` flags. - -## Usage - -```sh -arctl agent publish [agent-name|project-directory] [flags] -``` - -Examples: -```sh -# Publish from current directory (reads metadata from agent.yaml) -arctl agent publish - -# Publish from specified directory -arctl agent publish ./my-agent - -# Publish directly with name and git repo (no agent.yaml needed) -arctl agent publish my-agent \ - --git https://github.com/myorg/my-agent \ - --version 1.0.0 \ - --description "My agent" - -# Show what would be published -arctl agent publish --dry-run -``` - -## Command-specific flags - -```sh ---description string Agent description (when not using agent.yaml) ---dry-run Show what would be done without actually doing it ---git string Git repository URL (GitHub, GitLab, Bitbucket) ---overwrite Overwrite if the version is already published ---version string Version to publish (overrides manifest) -``` - -## Global flags -```sh --v, --verbose: Enable verbose output. --h, --help: Display help information for the command. -``` diff --git a/content/docs/reference/cli/arctl-agent-run.md b/content/docs/reference/cli/arctl-agent-run.md deleted file mode 100644 index 4717d41..0000000 --- a/content/docs/reference/cli/arctl-agent-run.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: arctl agent run -description: "Run an agent project locally with Docker Compose." -weight: 10 ---- - -Run an agent project locally via Docker compose. If the argument is a directory, -`arctl` uses the local files. Otherwise, it fetches the agent by name from the registry and -launches the interactive chat interface. - -## Usage - -```sh -arctl agent run [project-directory-or-agent-name] [flags] -``` - -Examples: -```sh -arctl agent run ./my-agent -arctl agent run dice -arctl agent run ./my-agent -e KEY=VALUE -``` - -## Command-specific flags - -```sh - --build Build the agent and MCP servers before running (default true) --e, --env stringArray Environment variables to set when running the agent (KEY=VALUE) -``` - -## Global flags -```sh --v, --verbose: Enable verbose output. --h, --help: Display help information for the command. -``` diff --git a/content/docs/reference/cli/arctl-agent-show.md b/content/docs/reference/cli/arctl-agent-show.md deleted file mode 100644 index a119928..0000000 --- a/content/docs/reference/cli/arctl-agent-show.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: arctl agent show -description: "Show detailed information about an agent." -weight: 10 ---- - -Shows detailed information about an agent. - -## Usage - -```sh -arctl agent show [flags] -``` - -Example: -```sh -arctl agent show my-agent -arctl agent show my-agent --output json -``` - -## Command-specific flags - -```sh --o, --output string: Output format (table, json) (default "table") -``` - -## Global flags -```sh --v, --verbose: Enable verbose output. --h, --help: Display help information for the command. -``` diff --git a/content/docs/reference/cli/arctl-apply.md b/content/docs/reference/cli/arctl-apply.md new file mode 100644 index 0000000..d85ab76 --- /dev/null +++ b/content/docs/reference/cli/arctl-apply.md @@ -0,0 +1,37 @@ +--- +title: arctl apply +description: "Apply one or more registry resources from a YAML file." +weight: 10 +--- + +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. + +## Usage + +```sh +arctl apply -f FILE [flags] +``` + +Examples: +```sh +arctl apply -f agent.yaml +arctl apply -f stack.yaml --dry-run +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) +``` + +## 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) +``` diff --git a/content/docs/reference/cli/arctl-build.md b/content/docs/reference/cli/arctl-build.md new file mode 100644 index 0000000..d618058 --- /dev/null +++ b/content/docs/reference/cli/arctl-build.md @@ -0,0 +1,40 @@ +--- +title: arctl build +description: "Build a Docker image for a declarative resource project." +weight: 10 +--- + +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. + +Supported resource kinds: `Agent`, `MCPServer` + +## Usage + +```sh +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 +``` + +## Command-specific flags + +```sh + --image string Docker image tag override (default: from spec.source.image / spec.source.package.origin.identifier) + --platform string Target platform (e.g. linux/amd64, linux/arm64) + --push Push the image after building +``` + +## 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) +``` diff --git a/content/docs/reference/cli/arctl-completion.md b/content/docs/reference/cli/arctl-completion.md index 994bfdd..cd08829 100644 --- a/content/docs/reference/cli/arctl-completion.md +++ b/content/docs/reference/cli/arctl-completion.md @@ -4,27 +4,100 @@ description: "Generate shell autocompletion scripts for arctl." weight: 10 --- -Generate shell autocompletion scripts. +Generate the autocompletion script for `arctl` for the specified shell. ## Usage ```sh -arctl completion [bash|zsh|fish|powershell] +arctl completion [command] ``` -Example: +Available sub-commands: `bash`, `fish`, `powershell`, `zsh` + +## bash + ```sh arctl completion bash ``` -## Command-specific flags +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 -No command-specific flags. +# macOS: +arctl completion bash > $(brew --prefix)/etc/bash_completion.d/arctl +``` -## Global flags +## 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 --v, --verbose: Enable verbose output. --h, --help: Display help information for the command. +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 +``` + +## 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) +``` diff --git a/content/docs/reference/cli/arctl-configure.md b/content/docs/reference/cli/arctl-configure.md index 27522e6..cc8b313 100644 --- a/content/docs/reference/cli/arctl-configure.md +++ b/content/docs/reference/cli/arctl-configure.md @@ -4,7 +4,9 @@ description: "Create the JSON configuration each client needs to connect to arct weight: 10 --- -Creates the .json configuration for each client, so it can 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 @@ -12,20 +14,27 @@ Creates the .json configuration for each client, so it can connect to `arctl`. arctl configure [client-name] [flags] ``` -Example: +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") ---url string: Custom MCP server URL (default: http://localhost:21212/mcp) + --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) ``` ## Global flags + ```sh --v, --verbose: Enable verbose output. --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) ``` diff --git a/content/docs/reference/cli/arctl-db-migrate.md b/content/docs/reference/cli/arctl-db-migrate.md new file mode 100644 index 0000000..c372ed3 --- /dev/null +++ b/content/docs/reference/cli/arctl-db-migrate.md @@ -0,0 +1,77 @@ +--- +title: arctl db migrate +description: "Apply, roll back, and inspect database migrations." +weight: 10 +--- + +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. + +```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. + +```sh +arctl db migrate status [flags] +``` + +Flags: +```sh +-o, --output string Output format: "text" (default) or "json" +``` + +## 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. + +```sh +arctl db migrate version +``` + +## Global flags + +```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. +``` diff --git a/content/docs/reference/cli/arctl-db.md b/content/docs/reference/cli/arctl-db.md new file mode 100644 index 0000000..4e90573 --- /dev/null +++ b/content/docs/reference/cli/arctl-db.md @@ -0,0 +1,21 @@ +--- +title: arctl db +description: "Database operations for the agent registry (migrations, inspection)." +weight: 10 +--- + +Database operations for the agent registry: running, rolling back, and inspecting database migrations. + +## Usage + +```sh +arctl db [command] +``` + +Available sub-commands: `migrate` + +## Global flags + +```sh +-h, --help Display help information for the command. +``` diff --git a/content/docs/reference/cli/arctl-delete.md b/content/docs/reference/cli/arctl-delete.md new file mode 100644 index 0000000..b61948b --- /dev/null +++ b/content/docs/reference/cli/arctl-delete.md @@ -0,0 +1,45 @@ +--- +title: arctl delete +description: "Delete a registry resource by type and name, or from a YAML file." +weight: 10 +--- + +Delete a registry resource. + +**File mode (declarative):** reads resources from a YAML file and sends `DELETE /v0/apply`. + +**Explicit mode:** specify the type and name directly. For taggable artifacts (agents, MCPs, skills, prompts), `--tag` selects an exact tag and defaults to `latest`. + +Supported types: `agent`, `mcp`, `skill`, `prompt`, `deployment` (plural and uppercase forms also accepted) + +## Usage + +```sh +arctl delete (TYPE NAME | -f FILE) [flags] +``` + +Examples: +```sh +arctl delete -f my-agent/agent.yaml +arctl delete -f my-server/mcp.yaml +arctl delete agent acme-summarizer --tag stable +arctl delete agent acme-summarizer --all-tags +arctl delete mcp acme-fetch --tag stable +arctl delete deployment team-a/my-agent +``` + +## Command-specific flags + +```sh + --all-tags Delete every tag of NAME (taggable artifact kinds only) +-f, --filename string YAML file to read resources from + --tag string Specific tag to delete (taggable artifact kinds only; defaults to latest) +``` + +## 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) +``` diff --git a/content/docs/reference/cli/arctl-deployments-create.md b/content/docs/reference/cli/arctl-deployments-create.md deleted file mode 100644 index 7c48be0..0000000 --- a/content/docs/reference/cli/arctl-deployments-create.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: arctl deployments create -description: "Create a deployment for an agent or MCP server from the registry." -weight: 10 ---- - -Create a deployment for an agent or MCP server from the registry. - -## Usage - -```sh -arctl deployments create [flags] -``` - -Example: -```sh -arctl deployments create my-agent --type agent --version latest -arctl deployments create my-agent --type agent --version 1.2.3 -arctl deployments create my-agent --type agent --provider-id kubernetes-default --namespace my-namespace -arctl deployments create my-mcp-server --type mcp --version 1.0.0 -arctl deployments create my-mcp-server --type mcp -e KEY=VALUE -a ARG=value -``` - -## Command-specific flags - -```sh ---type string: Resource type to deploy (agent or mcp) (required) ---version string: Version to deploy (default "latest") ---provider-id string: Deployment target provider ID (default "local") ---namespace string: Kubernetes namespace for deployment ---wait: Wait for the deployment to become ready before returning (default true) ---prefer-remote: Prefer using a remote source when available --e, --env stringArray: Environment variables to set (KEY=VALUE) --a, --arg stringArray: Runtime arguments for MCP servers (KEY=VALUE) ---header stringArray: HTTP headers for remote MCP servers (KEY=VALUE) -``` - -## Global flags -```sh --v, --verbose: Enable verbose output. --h, --help: Display help information for the command. -``` diff --git a/content/docs/reference/cli/arctl-deployments-delete.md b/content/docs/reference/cli/arctl-deployments-delete.md deleted file mode 100644 index 41ef655..0000000 --- a/content/docs/reference/cli/arctl-deployments-delete.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: arctl deployments delete -description: "Delete a deployment by its ID and tear down its associated resources." -weight: 10 ---- - -Delete a deployment by its ID. This removes the deployment record and tears down any associated resources. - -## Usage - -```sh -arctl deployments delete -``` - -Example: -```sh -arctl deployments delete abc12345 -arctl deployments delete abc12345-def6-7890-ghij-klmnopqrstuv -``` - -The deployment ID can be the full ID or a unique prefix (as shown in `arctl deployments list`). - -## Global flags -```sh --v, --verbose: Enable verbose output. --h, --help: Display help information for the command. -``` diff --git a/content/docs/reference/cli/arctl-deployments-list.md b/content/docs/reference/cli/arctl-deployments-list.md deleted file mode 100644 index dca31be..0000000 --- a/content/docs/reference/cli/arctl-deployments-list.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: arctl deployments list -description: "List all agent and MCP server deployments." -weight: 10 ---- - -List all deployments (agents and MCP servers). - -## Usage - -```sh -arctl deployments list [flags] -``` - -Example: -```sh -arctl deployments list -arctl deployments list --type agent -arctl deployments list --type mcp -arctl deployments list --status deployed -arctl deployments list --provider local -arctl deployments list -o json -``` - -## Command-specific flags - -```sh ---type string: Filter by resource type (agent or mcp) ---status string: Filter by deployment status (deploying, deployed, failed, cancelled, discovered) ---provider string: Filter by provider ID --o, --output string: Output format (table, json) (default "table") -``` - -## Global flags -```sh --v, --verbose: Enable verbose output. --h, --help: Display help information for the command. -``` diff --git a/content/docs/reference/cli/arctl-deployments-show.md b/content/docs/reference/cli/arctl-deployments-show.md deleted file mode 100644 index d275d02..0000000 --- a/content/docs/reference/cli/arctl-deployments-show.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: arctl deployments show -description: "Show detailed information about a deployment, including its status, provider, and endpoint URL." -weight: 10 ---- - -Show detailed information about a deployment, including its status, provider, environment variables, and endpoint URL. - -## Usage - -```sh -arctl deployments show [flags] -``` - -Example: -```sh -arctl deployments show eb2d8231 -arctl deployments show eb2d8231-def6-7890-ghij-klmnopqrstuv -arctl deployments show eb2d8231 -o json -``` - -The deployment ID can be the full ID or a unique prefix (as shown in `arctl deployments list`). - -## Command-specific flags - -```sh --o, --output string: Output format (table, json) (default "table") -``` - -## Global flags -```sh --v, --verbose: Enable verbose output. --h, --help: Display help information for the command. -``` diff --git a/content/docs/reference/cli/arctl-embeddings-generate.md b/content/docs/reference/cli/arctl-embeddings-generate.md deleted file mode 100644 index 705f3c7..0000000 --- a/content/docs/reference/cli/arctl-embeddings-generate.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: arctl embeddings generate -description: "Generate embeddings for existing servers and agents to backfill or refresh them." -weight: 10 ---- - -Generate embeddings for existing servers and agents (backfill or refresh). - -## Usage - -```sh -arctl embeddings generate [flags] -``` - -Examples: -```sh -arctl embeddings generate --servers --agents --update -arctl embeddings generate --dry-run -``` - -## Command-specific flags - -```sh ---agents Include agents when generating embeddings (default true) ---batch-size int Number of server versions processed per batch (default 100) ---dry-run Print planned changes without calling the embedding provider or writing to the database ---poll-interval duration Poll interval when not using streaming (default 2s) ---servers Include MCP servers when generating embeddings (default true) ---stream Use SSE streaming for progress updates (default true) ---update Regenerate embeddings even when the stored checksum matches -``` - -## Global flags -```sh --v, --verbose: Enable verbose output. --h, --help: Display help information for the command. -``` diff --git a/content/docs/reference/cli/arctl-embeddings.md b/content/docs/reference/cli/arctl-embeddings.md deleted file mode 100644 index 2267e04..0000000 --- a/content/docs/reference/cli/arctl-embeddings.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: arctl embeddings -description: "Manage semantic embeddings stored in agentregistry." -weight: 10 ---- - -Manage semantic embeddings stored in agentregistry. - -## Usage - -```sh -arctl embeddings [command] -``` - -## Available Commands - -- `generate`: Generate embeddings for existing servers and agents (backfill or refresh) - -## Global flags -```sh --v, --verbose: Enable verbose output. --h, --help: Display help information for the command. -``` diff --git a/content/docs/reference/cli/arctl-get.md b/content/docs/reference/cli/arctl-get.md new file mode 100644 index 0000000..06ae0f3 --- /dev/null +++ b/content/docs/reference/cli/arctl-get.md @@ -0,0 +1,55 @@ +--- +title: arctl get +description: "List or retrieve registry resources by type." +weight: 10 +--- + +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`) + +Use `arctl get all` to retrieve resources of every type. + +## Usage + +```sh +arctl get TYPE [NAME] [flags] +``` + +Examples: +```sh +arctl get all +arctl get agents +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 +arctl get agent acme-summarizer +arctl get agent acme-summarizer -o yaml +arctl get agent acme-summarizer --tag stable +arctl get agent acme-summarizer --all-tags +arctl get deployment team-a/acme-summarizer +arctl get deployments --origin discovered # list discovered (unmanaged) deployments +arctl get deployments --origin all # list managed and discovered +arctl get skills -o json +``` + +## Command-specific flags + +```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) +-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. +``` + +## 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) +``` diff --git a/content/docs/reference/cli/arctl-init-agent.md b/content/docs/reference/cli/arctl-init-agent.md new file mode 100644 index 0000000..b4d4ecf --- /dev/null +++ b/content/docs/reference/cli/arctl-init-agent.md @@ -0,0 +1,54 @@ +--- +title: arctl init agent +description: "Scaffold a new agent project with declarative YAML and framework stubs." +weight: 10 +--- + +Scaffold a new agent project. + +Picks a framework and 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: + +```sh +MCP_SERVERS_CONFIG=[{"name":"my-remote","type":"remote","url":"https://mcp.example.com/sse"}] +``` + +## Usage + +```sh +arctl init agent NAME [flags] +``` + +Examples: +```sh +arctl init agent myagent +arctl init agent myagent --framework adk --language python +arctl init agent myagent --local-mcp ../my-mcp +``` + +## Command-specific flags + +```sh + --description string Agent description + --framework string Framework (e.g. adk). Skips picker. + --git string Git repository URL + --git-branch string Git branch to record on the agent's source repository + --git-commit string Git commit SHA to pin the agent's source repository to + --image string Image tag override + --language string Language (e.g. python). Skips picker. + --local-mcp strings Path to a sibling MCP project; wires it into .env so the local agent can reach it. Repeatable. + --mcp strings Registry MCP server ref (name@version). Repeatable. + --model-name string Model name + --model-provider string Model provider +``` + +## 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) +``` diff --git a/content/docs/reference/cli/arctl-init-mcp.md b/content/docs/reference/cli/arctl-init-mcp.md new file mode 100644 index 0000000..0f3eb0f --- /dev/null +++ b/content/docs/reference/cli/arctl-init-mcp.md @@ -0,0 +1,43 @@ +--- +title: arctl init mcp +description: "Scaffold a new MCP server project with declarative YAML and framework stubs." +weight: 10 +--- + +Scaffold a new MCP server project. + +Picks a framework and language interactively (or via `--framework` / `--language`). + +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). + +## Usage + +```sh +arctl init mcp NAME [flags] +``` + +Examples: +```sh +arctl init mcp my-mcp +arctl init mcp my-mcp --framework fastmcp --language python +arctl init mcp my-stdio --framework fastmcp --language python --transport stdio +``` + +## Command-specific flags + +```sh + --description string MCP server description + --framework string Framework. Skips picker. + --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. +``` + +## 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) +``` diff --git a/content/docs/reference/cli/arctl-init-prompt.md b/content/docs/reference/cli/arctl-init-prompt.md new file mode 100644 index 0000000..56cf22d --- /dev/null +++ b/content/docs/reference/cli/arctl-init-prompt.md @@ -0,0 +1,38 @@ +--- +title: arctl init prompt +description: "Create a new declarative prompt YAML using the ar.dev/v1alpha1 format." +weight: 10 +--- + +Create a new `.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 +``` + +## Usage + +```sh +arctl init prompt NAME [flags] +``` + +Examples: +```sh +arctl init prompt my-prompt +arctl init prompt my-prompt --description "System prompt for summarization" +``` + +## Command-specific flags + +```sh + --content string Initial prompt content (default "You are a helpful assistant.") + --description string Prompt description +``` + +## 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) +``` diff --git a/content/docs/reference/cli/arctl-init-skill.md b/content/docs/reference/cli/arctl-init-skill.md new file mode 100644 index 0000000..8a2d4aa --- /dev/null +++ b/content/docs/reference/cli/arctl-init-skill.md @@ -0,0 +1,37 @@ +--- +title: arctl init skill +description: "Scaffold a new skill project with declarative YAML and source stubs." +weight: 10 +--- + +Scaffold a new skill project. Creates a project directory containing a declarative `skill.yaml` (`ar.dev/v1alpha1`) and source stubs. + +The generated `skill.yaml` can be applied directly: +```sh +arctl apply -f NAME/skill.yaml +``` + +## Usage + +```sh +arctl init skill NAME [flags] +``` + +Examples: +```sh +arctl init skill my-skill +arctl init skill my-skill --description "Text summarizer" +``` + +## Command-specific flags + +```sh + --description string Skill description +``` + +## 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) +``` diff --git a/content/docs/reference/cli/arctl-init.md b/content/docs/reference/cli/arctl-init.md new file mode 100644 index 0000000..df79af7 --- /dev/null +++ b/content/docs/reference/cli/arctl-init.md @@ -0,0 +1,51 @@ +--- +title: arctl init +description: "Scaffold a new declarative resource project (agent, MCP server, skill, or prompt)." +weight: 10 +--- + +Scaffold a new project. The generated YAML uses the `ar.dev/v1alpha1` declarative format and can be applied directly with `arctl apply`. + +Supported types: +- `agent NAME` — framework + language picker +- `mcp NAME` — framework + language picker +- `skill NAME` +- `prompt NAME` + +Run `arctl init` with no arguments for an interactive picker that selects the resource kind. + +## Usage + +```sh +arctl init TYPE NAME [flags] +``` + +Examples: +```sh +arctl init agent myagent +arctl init agent myagent --framework adk --language python +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 +``` + +## Command-specific flags + +```sh + --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. +``` + +## Sub-commands + +- [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 diff --git a/content/docs/reference/cli/arctl-mcp-add-tool.md b/content/docs/reference/cli/arctl-mcp-add-tool.md deleted file mode 100644 index dd9b1ad..0000000 --- a/content/docs/reference/cli/arctl-mcp-add-tool.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: arctl mcp add-tool -description: "Generate an MCP tool scaffold." -weight: 10 ---- - -Generate an MCP tool scaffold. - -This command creates a new tool file in `src/tools/` directory with a generic template. -The tool is automatically discovered and loaded when the MCP server starts. - -Each tool is a Python file containing a function decorated with `@mcp.tool()`. -The function uses the `@mcp.tool()` decorator from FastMCP. - -## Usage - -```sh -arctl mcp add-tool [tool-name] [flags] -``` - -Example: -```sh -arctl mcp add-tool weather -arctl mcp add-tool database --description "Database operations tool" -arctl mcp add-tool weather --force -``` - -## Command-specific flags - -```sh --d, --description string: Tool description --f, --force: Overwrite existing tool file --i, --interactive: Interactive tool creation ---project-dir string: Project directory (default: current directory) -``` - -## Global flags -```sh --v, --verbose: Enable verbose output. --h, --help: Display help information for the command. -``` diff --git a/content/docs/reference/cli/arctl-mcp-build.md b/content/docs/reference/cli/arctl-mcp-build.md deleted file mode 100644 index 8642911..0000000 --- a/content/docs/reference/cli/arctl-mcp-build.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: arctl mcp build -description: "Build an MCP server from the current project." -weight: 10 ---- - -Build an MCP server from the current project. - -This command detects the project type and builds the appropriate MCP server Docker image. - -## Usage - -```sh -arctl mcp build [flags] -``` - -Examples: -```sh -arctl mcp build # Build Docker image from current directory -arctl mcp build ./my-project # Build Docker image from specific directory -arctl mcp build --image docker.io/myorg/my-mcp:v1.0.0 --push -``` - -## Command-specific flags - -```sh --n, --image string Full image specification (e.g., docker.io/myorg/my-mcp:v1.0.0) - --platform string Target platform (e.g., linux/amd64,linux/arm64) - --push Push the image to the container registry, specified by --image -``` - -## Global flags -```sh --v, --verbose: Enable verbose output. --h, --help: Display help information for the command. -``` diff --git a/content/docs/reference/cli/arctl-mcp-delete.md b/content/docs/reference/cli/arctl-mcp-delete.md deleted file mode 100644 index baf20f7..0000000 --- a/content/docs/reference/cli/arctl-mcp-delete.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: arctl mcp delete -description: "Delete an MCP server from agentregistry." -weight: 10 ---- - -Delete an MCP server from agentregistry. - -## Usage - -```sh -arctl mcp delete [flags] -``` - -Example: -```sh -arctl mcp delete my-server --version 1.0.0 -``` - -## Command-specific flags - -```sh ---version string: Specify the version to delete (required) -``` - -## Global flags -```sh --v, --verbose: Enable verbose output. --h, --help: Display help information for the command. -``` diff --git a/content/docs/reference/cli/arctl-mcp-init-go.md b/content/docs/reference/cli/arctl-mcp-init-go.md deleted file mode 100644 index 70717f8..0000000 --- a/content/docs/reference/cli/arctl-mcp-init-go.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: arctl mcp init go -description: "Initialize a new MCP server project using the mcp-go framework." -weight: 10 ---- - -Initialize a new MCP server project using the `mcp-go` framework. - -This command creates a new directory with a basic `mcp-go` project structure, -including a `go.mod` file, a `main.go` file, and an example tool. - -You must provide a valid Go module name for the project. - -## Usage - -```sh -arctl mcp init go [project-name] [flags] -``` - -Example: -```sh -arctl mcp init go my-mcp-server --go-module-name github.com/my-org/my-project -``` - -## Command-specific flags - -```sh ---go-module-name string: The Go module name for the project (e.g., github.com/my-org/my-project) -``` - -## Global flags -```sh ---author string: Author name for the project ---description string: Description for the project ---email string: Author email for the project ---force: Overwrite existing directory ---no-git: Skip git initialization ---non-interactive: Run in non-interactive mode --v, --verbose: Enable verbose output. --h, --help: Display help information for the command. -``` diff --git a/content/docs/reference/cli/arctl-mcp-init-python.md b/content/docs/reference/cli/arctl-mcp-init-python.md deleted file mode 100644 index 5906c42..0000000 --- a/content/docs/reference/cli/arctl-mcp-init-python.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: arctl mcp init python -description: "Initialize a new MCP server project using the fastmcp-python framework." -weight: 10 ---- - -Initialize a new MCP server project by using the `fastmcp-python` framework. - -This command creates a new directory with a basic `fastmcp-python` project structure, -including a `pyproject.toml` file, a `main.py` file, and an example tool. - -## Usage - -```sh -arctl mcp init python [project-name] [flags] -``` - -Example: -```sh -arctl mcp init python my-mcp-server -arctl mcp init python my-mcp-server --author "John Doe" --email "john@example.com" -``` - -## Command-specific flags - -No command-specific flags beyond the positional arguments. - -## Global flags -```sh ---author string: Author name for the project ---description string: Description for the project ---email string: Author email for the project ---force: Overwrite existing directory ---no-git: Skip git initialization ---non-interactive: Run in non-interactive mode --v, --verbose: Enable verbose output. --h, --help: Display help information for the command. -``` diff --git a/content/docs/reference/cli/arctl-mcp-init.md b/content/docs/reference/cli/arctl-mcp-init.md deleted file mode 100644 index 5e83158..0000000 --- a/content/docs/reference/cli/arctl-mcp-init.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: arctl mcp init -description: "Initialize a new MCP server project with dynamic tool loading." -weight: 10 ---- - -Initialize a new MCP server project with dynamic tool loading. - -This command provides subcommands to initialize a new MCP server project -by using one of the supported frameworks. - -## Usage - -```sh -arctl mcp init [project-type] [project-name] [flags] -arctl mcp init [command] -``` - -## Available Commands - -- `go`: Initialize a new Go MCP server project -- `python`: Initialize a new Python MCP server project - -## Command-specific flags - -```sh ---author string Author name for the project ---description string Description for the project ---email string Author email for the project ---force Overwrite existing directory ---no-git Skip git initialization ---non-interactive Run in non-interactive mode ---version string Version for the project (default: 0.1.0) -``` - -## Global flags -```sh --v, --verbose: Enable verbose output. --h, --help: Display help information for the command. -``` diff --git a/content/docs/reference/cli/arctl-mcp-list.md b/content/docs/reference/cli/arctl-mcp-list.md deleted file mode 100644 index 80ad5fc..0000000 --- a/content/docs/reference/cli/arctl-mcp-list.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: arctl mcp list -description: "List all Model Context Protocol (MCP) servers published in the registry." -weight: 10 ---- - -Lists all Model Context Protocol (MCP) servers published in the registry. - -## Usage - -```sh -arctl mcp list [flags] -``` - -Examples: -```sh -arctl mcp list -arctl mcp list --type npm -arctl mcp list --sortBy version --output json -``` - -## Command-specific flags - -```sh --a, --all Show all items without pagination --o, --output string Output format (table, json, yaml) (default "table") --p, --page-size int Number of items per page (default 15) --s, --sortBy string Sort by column (name, version, type, status, updated) (default "name") --t, --type string Filter by registry type (e.g., npm, pypi, oci, sse, streamable-http) -``` - -## Global flags -```sh --v, --verbose: Enable verbose output. --h, --help: Display help information for the command. -``` diff --git a/content/docs/reference/cli/arctl-mcp-publish.md b/content/docs/reference/cli/arctl-mcp-publish.md deleted file mode 100644 index 0d42475..0000000 --- a/content/docs/reference/cli/arctl-mcp-publish.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: arctl mcp publish -description: "Publish an MCP server to the registry." -weight: 10 ---- - -Publish an MCP server to the registry. - -This command supports two modes: - -1. **Package-based** (installable artifact): Requires `--type` and `--package-id`. Use for servers distributed via npm, PyPI, or OCI. -2. **Remote-only** (already-deployed endpoint): Use `--remote-url` for servers already running in the cloud. No `--type` or `--package-id` needed. - -If no argument is provided and `mcp.yaml` exists in the current directory, metadata is read from it. - -## Usage - -```sh -arctl mcp publish [server-name|local-path] [flags] -``` - -Examples: -```sh -# Publish a remote MCP server hosted on Databricks (no package to install) -arctl mcp publish com.databricks/unity-catalog \ - --remote-url https://my-workspace.cloud.databricks.com/mcp \ - --version 1.0.0 \ - --description "Databricks Unity Catalog MCP server" - -# Publish from current folder (reads metadata from mcp.yaml) -arctl mcp publish \ - --type oci \ - --package-id docker.io/myorg/my-server:1.0.0 - -# Publish an OCI image with explicit server name -arctl mcp publish myorg/my-server \ - --type oci \ - --package-id docker.io/myorg/my-server:1.0.0 \ - --version 1.0.0 \ - --description "My MCP server" - -# Publish an NPM package -arctl mcp publish myorg/filesystem-server \ - --type npm \ - --package-id @modelcontextprotocol/server-filesystem \ - --version 1.0.0 \ - --description "Filesystem MCP server" \ - --arg /path/to/directory - -# Publish a PyPI package -arctl mcp publish myorg/server \ - --type pypi \ - --package-id mcp-server-package \ - --version 1.0.0 \ - --description "Python MCP server" -``` - -## Command-specific flags - -```sh ---arg stringArray Package argument (repeatable) ---description string Server description ---dry-run Show what would be done without actually doing it ---git string Git repository URL (GitHub, GitLab, Bitbucket) ---overwrite Overwrite if the version is already published ---package-id string Package identifier (e.g., docker.io/org/image:tag, @mcp/server) ---package-version string Package version (defaults to --version) ---remote-url string URL of an already-deployed remote MCP server (e.g. https://my-workspace.databricks.com/mcp) ---transport string Transport type: stdio or streamable-http (package mode); streamable-http or sse (--remote-url mode) ---transport-url string Transport URL for streamable-http transport ---type string Package registry type: npm, pypi, or oci ---version string Server version -``` - -## Global flags -```sh --v, --verbose: Enable verbose output. --h, --help: Display help information for the command. -``` diff --git a/content/docs/reference/cli/arctl-mcp-run.md b/content/docs/reference/cli/arctl-mcp-run.md deleted file mode 100644 index dbd5652..0000000 --- a/content/docs/reference/cli/arctl-mcp-run.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: arctl mcp run -description: "Run an MCP server locally." -weight: 10 ---- - -Run an MCP server locally. - -You can run either: -- A server from the registry by name (e.g., `arctl mcp run @modelcontextprotocol/server-everything`) -- A local MCP project by path (e.g., `arctl mcp run .` or `arctl mcp run ./my-mcp-server`) - -For local projects, the server is automatically built before running. Use `--no-build` to skip the build step. - -## Usage - -```sh -arctl mcp run [flags] -``` - -Examples: -```sh -arctl mcp run @modelcontextprotocol/server-everything -arctl mcp run ./my-mcp-server --inspector -arctl mcp run . -e KEY=VALUE --arg ARG=value -``` - -## Command-specific flags - -```sh - --arg stringArray Runtime arguments (key=value) - --build Build the MCP server before running (default true) --e, --env stringArray Environment variables (key=value) - --header stringArray Headers for remote servers (key=value) - --inspector Launch MCP Inspector to interact with the server - --verbose Enable verbose logging - --version string Specify the version of the server to run --y, --yes Automatically accept all prompts (use default values) -``` - -## Global flags -```sh --h, --help: Display help information for the command. -``` diff --git a/content/docs/reference/cli/arctl-mcp-show.md b/content/docs/reference/cli/arctl-mcp-show.md deleted file mode 100644 index a14a294..0000000 --- a/content/docs/reference/cli/arctl-mcp-show.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: arctl mcp show -description: "Show detailed information about an MCP server." -weight: 10 ---- - -Shows detailed information about an MCP server. - -## Usage - -```sh -arctl mcp show [flags] -``` - -Example: -```sh -arctl mcp show my-server -arctl mcp show my-server --version 1.0.0 --output json -``` - -## Command-specific flags - -```sh --o, --output string: Output format (table, json) (default "table") ---version string: Show specific version of the server -``` - -## Global flags -```sh --v, --verbose: Enable verbose output. --h, --help: Display help information for the command. -``` diff --git a/content/docs/reference/cli/arctl-prompt-delete.md b/content/docs/reference/cli/arctl-prompt-delete.md deleted file mode 100644 index 7d87a94..0000000 --- a/content/docs/reference/cli/arctl-prompt-delete.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: arctl prompt delete -description: "Delete a prompt version from agentregistry." -weight: 10 ---- - -Delete a prompt version from agentregistry. - -## Usage - -```sh -arctl prompt delete --version -``` - -Example: -```sh -arctl prompt delete code-review --version 1.0.0 -``` - -## Command-specific flags - -```sh ---version string: Specify the version to delete (required) -``` - -## Global flags -```sh --v, --verbose: Enable verbose output. --h, --help: Display help information for the command. -``` diff --git a/content/docs/reference/cli/arctl-prompt-list.md b/content/docs/reference/cli/arctl-prompt-list.md deleted file mode 100644 index 2910047..0000000 --- a/content/docs/reference/cli/arctl-prompt-list.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: arctl prompt list -description: "List prompts published to agentregistry." -weight: 10 ---- - -List prompts published to agentregistry. - -## Usage - -```sh -arctl prompt list [flags] -``` - -Example: -```sh -arctl prompt list -arctl prompt list --all --output json -``` - -## Command-specific flags - -```sh --a, --all: Show all items without pagination --o, --output string: Output format (table, json) (default "table") --p, --page-size int: Number of items per page (default 15) -``` - -## Global flags -```sh --v, --verbose: Enable verbose output. --h, --help: Display help information for the command. -``` diff --git a/content/docs/reference/cli/arctl-prompt-publish.md b/content/docs/reference/cli/arctl-prompt-publish.md deleted file mode 100644 index bc2ac32..0000000 --- a/content/docs/reference/cli/arctl-prompt-publish.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: arctl prompt publish -description: "Publish a prompt to agentregistry from a plain text or YAML file." -weight: 10 ---- - -Publish a prompt to agentregistry. The prompt can be provided as a plain text file or a YAML file. - -When publishing from a text file, the `--name` and `--version` flags are required. When publishing from a YAML file (`.yaml` or `.yml`), the name and version are read from the file but can be overridden with flags. - -## Usage - -```sh -arctl prompt publish [flags] -``` - -Example: -```sh -arctl prompt publish system-prompt.txt --name my-prompt --version 1.0.0 -arctl prompt publish system-prompt.txt --name my-prompt --version 1.0.0 --description "System prompt for code review" -arctl prompt publish prompt.yaml -arctl prompt publish prompt.yaml --version 2.0.0 -``` - -## Command-specific flags - -```sh ---name string: Prompt name (required for text files) ---version string: Prompt version (required for text files) ---description string: Prompt description ---dry-run: Preview what will be published without publishing the prompt -``` - -## Global flags -```sh --v, --verbose: Enable verbose output. --h, --help: Display help information for the command. -``` diff --git a/content/docs/reference/cli/arctl-prompt-show.md b/content/docs/reference/cli/arctl-prompt-show.md deleted file mode 100644 index f7ddfe3..0000000 --- a/content/docs/reference/cli/arctl-prompt-show.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: arctl prompt show -description: "Show details of a prompt published to agentregistry." -weight: 10 ---- - -Show details of a prompt that is published to agentregistry. - -## Usage - -```sh -arctl prompt show [flags] -``` - -Example: -```sh -arctl prompt show code-review -arctl prompt show code-review --output json -``` - -## Command-specific flags - -```sh --o, --output string: Output format (table, json) (default "table") -``` - -## Global flags -```sh --v, --verbose: Enable verbose output. --h, --help: Display help information for the command. -``` diff --git a/content/docs/reference/cli/arctl-pull.md b/content/docs/reference/cli/arctl-pull.md new file mode 100644 index 0000000..69060be --- /dev/null +++ b/content/docs/reference/cli/arctl-pull.md @@ -0,0 +1,38 @@ +--- +title: arctl pull +description: "Fetch a registry resource's source repository to a local directory." +weight: 10 +--- + +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). + +Supported types: `agent`, `mcp`, `skill` + +## Usage + +```sh +arctl pull TYPE NAME [DIRECTORY] [flags] +``` + +Examples: +```sh +arctl pull agent myagent +arctl pull mcp myserver ./vendor/myserver +arctl pull skill myskill --tag stable +``` + +## Command-specific flags + +```sh + --tag string Specific tag to pull +``` + +## 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) +``` diff --git a/content/docs/reference/cli/arctl-run.md b/content/docs/reference/cli/arctl-run.md new file mode 100644 index 0000000..4ab70d9 --- /dev/null +++ b/content/docs/reference/cli/arctl-run.md @@ -0,0 +1,50 @@ +--- +title: arctl run +description: "Run the agent or MCP server defined in the current project directory." +weight: 10 +--- + +Run the agent or MCP server defined by the declarative YAML in the project directory (defaults to `.`). + +Reads `arctl.yaml` to look up the matching framework by `(framework, language)` and dispatches to its run command. Loads `.env` (if present) and validates that the framework's required env vars are set. + +**For 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 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. + +## Usage + +```sh +arctl run [DIRECTORY] [flags] +``` + +Examples: +```sh +arctl run +arctl run ./myagent +arctl run -e FOO=bar -e BAZ=qux +arctl run --no-chat # agent without chat +arctl run --watch # iterative dev loop +arctl run mymcp --inspector # MCP with MCP Inspector launched +``` + +## Command-specific flags + +```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) +``` + +## 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) +``` diff --git a/content/docs/reference/cli/arctl-skill-build.md b/content/docs/reference/cli/arctl-skill-build.md deleted file mode 100644 index d8d8029..0000000 --- a/content/docs/reference/cli/arctl-skill-build.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: arctl skill build -description: "Build a skill as a Docker image from a local skill folder containing a SKILL.md file." -weight: 10 ---- - -Build a skill as a Docker image from a local skill folder containing a `SKILL.md` file. - -This command reads the `SKILL.md` frontmatter to determine the skill name, builds a Docker image, and optionally pushes it to a registry. If the given directory contains multiple subdirectories with `SKILL.md` files, all matching skills are built. - -## Usage - -```sh -arctl skill build [flags] -``` - -Examples: -```sh -arctl skill build ./my-skill --image docker.io/myorg/my-skill:v1.0.0 -arctl skill build ./my-skill --image docker.io/myorg/my-skill:v1.0.0 --push -arctl skill build ./my-skill --image docker.io/myorg/my-skill:v1.0.0 --platform linux/amd64 -``` - -## Command-specific flags - -```sh ---image string: Full image specification (e.g., docker.io/myorg/my-skill:v1.0.0) ---platform string: Target platform for Docker build (e.g., linux/amd64, linux/arm64) ---push: Push the image to the registry -``` - -## Global flags -```sh --v, --verbose: Enable verbose output. --h, --help: Display help information for the command. -``` diff --git a/content/docs/reference/cli/arctl-skill-delete.md b/content/docs/reference/cli/arctl-skill-delete.md deleted file mode 100644 index 1beb7e4..0000000 --- a/content/docs/reference/cli/arctl-skill-delete.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: arctl skill delete -description: "Delete a skill from agentregistry." -weight: 10 ---- - -Delete a skill from agentregistry. - -## Usage - -```sh -arctl skill delete [flags] -``` - -Example: -```sh -arctl skill delete my-skill --version 1.0.0 -``` - -## Command-specific flags - -```sh ---version string: Specify the version to delete (required) -``` - -## Global flags -```sh --v, --verbose: Enable verbose output. --h, --help: Display help information for the command. -``` diff --git a/content/docs/reference/cli/arctl-skill-init.md b/content/docs/reference/cli/arctl-skill-init.md deleted file mode 100644 index e301bd7..0000000 --- a/content/docs/reference/cli/arctl-skill-init.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: arctl skill init -description: "Initialize a new agentic skill project." -weight: 10 ---- - -Initialize a new agentic skill project. - -## Usage - -```sh -arctl skill init [skill-name] [flags] -``` - -Examples: -```sh -arctl skill init my-skill -arctl skill init my-skill --empty --force -arctl skill init my-skill --output-dir ./skills -``` - -## Command-specific flags - -```sh ---empty Create an empty skill project ---force Overwrite existing directory ---no-git Skip git initialization ---output-dir string Output directory for the skill project (default: current directory under the skill name) ---verbose Enable verbose output during initialization -``` - -## Global flags -```sh --h, --help: Display help information for the command. -``` diff --git a/content/docs/reference/cli/arctl-skill-list.md b/content/docs/reference/cli/arctl-skill-list.md deleted file mode 100644 index 3ee3749..0000000 --- a/content/docs/reference/cli/arctl-skill-list.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: arctl skill list -description: "List available skills in agentregistry." -weight: 10 ---- - -List available skills in agentregistry. - -## Usage - -```sh -arctl skill list [flags] -``` - -Example: -```sh -arctl skill list -arctl skill list --all --output json -arctl skill list --page-size 20 -``` - -## Command-specific flags - -```sh --a, --all: Show all items without pagination --o, --output string: Output format (table, json, yaml) (default "table") --p, --page-size int: Number of items per page (default 15) -``` - -## Global flags -```sh --v, --verbose: Enable verbose output. --h, --help: Display help information for the command. -``` diff --git a/content/docs/reference/cli/arctl-skill-publish.md b/content/docs/reference/cli/arctl-skill-publish.md deleted file mode 100644 index c4109ec..0000000 --- a/content/docs/reference/cli/arctl-skill-publish.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -title: arctl skill publish -description: "Publish a skill to the registry." -weight: 10 ---- - -Publish a skill to the registry. - -This command supports multiple modes: - -1. **From a local skill folder** (with `SKILL.md`): Reads metadata from the local file and publishes with a Git repository reference or a pre-built Docker image reference. -2. **Direct registration with Git** (without `SKILL.md`): Registers a skill by name using `--git` and `--version` flags. -3. **Direct registration with Docker** (without `SKILL.md`): Registers a skill by name using `--docker-image` and `--version` flags. - -## Usage - -```sh -arctl skill publish [flags] -``` - -Examples: -```sh -# Publish from a local folder with a Git repository reference -arctl skill publish ./my-skill --git https://github.com/myorg/repo --version 1.0.0 - -# Publish from a local folder with a pre-built Docker image -arctl skill publish ./my-skill --docker-image docker.io/myorg/my-skill:v1.0.0 --version 1.0.0 - -# Register directly from a Git repository (no local files needed) -arctl skill publish my-skill \ - --git https://github.com/myorg/repo/tree/main/skills/my-skill \ - --version 1.0.0 \ - --description "My remote skill" - -# Register directly with a pre-built Docker image (no local files needed) -arctl skill publish my-skill \ - --docker-image docker.io/myorg/my-skill:v1.0.0 \ - --version 1.0.0 \ - --description "My Docker skill" - -# Preview what will be published without publishing the skill -arctl skill publish ./my-skill --git https://github.com/myorg/repo --version 1.0.0 --dry-run -``` - -## Command-specific flags - -```sh ---description string Skill description (optional, used with direct registration) ---docker-image string Docker image URL (e.g., docker.io/myorg/my-skill:v1.0.0) ---dry-run Show what would be done without actually doing it ---git string Git repository URL. Supports tree URLs: https://github.com/owner/repo/tree/branch/path ---version string Version to publish (required for --git or --docker-image) -``` - -> [!NOTE] -> The `--git` and `--docker-image` flags are mutually exclusive. One of them is required. - -> [!TIP] -> To build a skill as a Docker image, use [`arctl skill build`](/docs/reference/cli/arctl-skill-build/) instead. - -## Global flags -```sh --v, --verbose: Enable verbose output. --h, --help: Display help information for the command. -``` diff --git a/content/docs/reference/cli/arctl-skill-pull.md b/content/docs/reference/cli/arctl-skill-pull.md deleted file mode 100644 index 0801d58..0000000 --- a/content/docs/reference/cli/arctl-skill-pull.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: arctl skill pull -description: "Pull a skill from agentregistry and extract its contents to a local directory." -weight: 10 ---- - -Pull a skill from agentregistry and extract its contents to a local directory. Supports skills packaged as Docker images or hosted in GitHub repositories. - -If no output directory is specified, the skill is automatically extracted to `./skills/`. - -## Usage - -```sh -arctl skill pull [output-directory] [flags] -``` - -Examples: -```sh -# Pull a skill to the default location (./skills/my-skill) -arctl skill pull my-skill - -# Pull to a custom directory -arctl skill pull my-skill ./my-output-dir - -# Pull a specific version -arctl skill pull my-skill --version 1.0.0 -``` - -## Command-specific flags - -```sh ---version string Version to pull (if not specified and multiple versions exist, you will be prompted) -``` - -## Global flags -```sh --v, --verbose: Enable verbose output. --h, --help: Display help information for the command. -``` diff --git a/content/docs/reference/cli/arctl-skill-show.md b/content/docs/reference/cli/arctl-skill-show.md deleted file mode 100644 index 8bfbb11..0000000 --- a/content/docs/reference/cli/arctl-skill-show.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: arctl skill show -description: "Show detailed information about a skill." -weight: 10 ---- - -Shows detailed information about a skill. - -## Usage - -```sh -arctl skill show [flags] -``` - -Example: -```sh -arctl skill show my-skill -arctl skill show my-skill --output json -``` - -## Command-specific flags - -```sh --o, --output string: Output format (table, json) (default "table") -``` - -## Global flags -```sh --v, --verbose: Enable verbose output. --h, --help: Display help information for the command. -``` diff --git a/content/docs/reference/cli/arctl-version.md b/content/docs/reference/cli/arctl-version.md index 02cd312..48d2ccb 100644 --- a/content/docs/reference/cli/arctl-version.md +++ b/content/docs/reference/cli/arctl-version.md @@ -21,10 +21,13 @@ arctl version --json ## Command-specific flags ```sh ---json Output version information in JSON format + --json Output version information in JSON format ``` ## 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) ``` diff --git a/content/docs/reference/cli/arctl-wait.md b/content/docs/reference/cli/arctl-wait.md new file mode 100644 index 0000000..c29d0fb --- /dev/null +++ b/content/docs/reference/cli/arctl-wait.md @@ -0,0 +1,47 @@ +--- +title: arctl wait +description: "Wait for a registry resource to reach a target state." +weight: 10 +--- + +Wait for a registry resource to reach a target state. + +Only `deployment` resources are currently supported. + +**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 + +**Timeout regimes:** +- `--timeout=5m` (default) — wait up to 5 minutes +- `--timeout=0` — poll once and return the current state +- `--timeout=-1` — wait forever + +## Usage + +```sh +arctl wait TYPE NAME [flags] +``` + +Examples: +```sh +arctl wait deployment aws-v1 +arctl wait deployment team-a/aws-v1 +arctl wait deployment aws-v1 --for=failed +arctl wait deployment aws-v1 --for=delete --timeout=10m +``` + +## Command-specific flags + +```sh + --for string Target state to wait for: deployed, failed, undeployed, delete (default "deployed") + --timeout duration Maximum time to wait. 0 polls once and exits; negative waits forever. (default 5m0s) +``` + +## 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) +``` diff --git a/hugo_stats.json b/hugo_stats.json index d012e87..23ad9bc 100644 --- a/hugo_stats.json +++ b/hugo_stats.json @@ -333,8 +333,6 @@ "hx:mb-16", "hx:mb-4", "hx:mb-8", - "hx:md:block", - "hx:md:dark:block", "hx:md:grid-cols-2", "hx:md:hidden", "hx:md:inline-flex", @@ -478,6 +476,7 @@ "qs-step-num", "quickstart", "quickstart-steps", + "reuse-image-nodark", "right", "section", "section-card", @@ -532,6 +531,7 @@ "terminal-title", "theme-toggle", "tick", + "toggle-dark", "toggle-light", "top", "url" @@ -550,8 +550,8 @@ "agents", "ar-orbit", "artifact-registry-infrastructure", - "available-commands", "backToTop", + "bash", "bb-panel", "bb-panel-desc", "bb-panel-link", @@ -572,6 +572,12 @@ "create-an-agent", "create-an-mcp-server", "data-enrichment", + "db-migrate-down", + "db-migrate-force", + "db-migrate-goto", + "db-migrate-status", + "db-migrate-up", + "db-migrate-version", "deploy", "deploy-the-agent", "deploy-the-mcp-server", @@ -579,23 +585,25 @@ "disclosures", "discovery", "discovery-across-environments", + "docker", "evaluation", "example", "explore-the-ui", "faqs", "favicon-svg", "features", + "fish", "from-the-registry", "gateway", "get-started", "global-flags", "governance-and-approval", - "helm-chart-configuration", "how-agentregistry-fills-the-gaps", "how-it-works", "install", - "install-arctl", + "install-the-arctl-cli", "install-with-helm", + "kubernetes", "learn-more", "mobile-icons-menu", "mobile-icons-toggle", @@ -605,6 +613,7 @@ "option-2-publish-from-a-github-repository-with-local-folder", "option-3-direct-registration-with-github-no-local-files-needed", "option-4-direct-registration-with-docker-image-no-local-files-needed", + "powershell", "preview-appbar", "prompts", "public-disclosure", @@ -619,21 +628,27 @@ "run-the-agent", "run-the-mcp-server", "servers", - "set-up-postgresql", "setup", "skills", "solo-back-to-top", "specify-a-version", + "step-1-create-the-agentregistry-database", + "step-2-configure-agentregistry", + "sub-commands", "tabs-panel-tabs-00-0", "tabs-panel-tabs-00-1", "tabs-panel-tabs-02-0", "tabs-panel-tabs-02-1", + "tabs-panel-tabs-03-0", + "tabs-panel-tabs-03-1", "tabs-panel-tabs-08-0", "tabs-panel-tabs-08-1", "tabs-tab-tabs-00-0", "tabs-tab-tabs-00-1", "tabs-tab-tabs-02-0", "tabs-tab-tabs-02-1", + "tabs-tab-tabs-03-0", + "tabs-tab-tabs-03-1", "tabs-tab-tabs-08-0", "tabs-tab-tabs-08-1", "terminal", @@ -642,7 +657,8 @@ "theme-toggle", "updates-and-questions", "usage", - "verify-the-published-skill" + "verify-the-published-skill", + "zsh" ] } } diff --git a/layouts/index.html b/layouts/index.html index 42c3f96..7d9b65b 100644 --- a/layouts/index.html +++ b/layouts/index.html @@ -540,7 +540,7 @@
Related
agentgateway kagent kgateway - MCP spec + MCP spec