> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gp.scale.com/llms.txt
> Use this file to discover all available pages before exploring further.

# sgpctl CLI

> Build, deploy, and observe Agentex agents from your terminal with sgpctl agentex-cloud.

## Overview

`sgpctl` is the command-line interface for managing Agentex cloud builds and deployments. It covers the same operations available through the SGP dashboard and the API/SDK, packaged for terminal workflows.

The CLI is organized under `sgpctl agentex-cloud` with two subcommand groups:

* **`build`**: submit cloud builds, list builds, stream build logs, and cancel running builds.
* **`deploy`**: submit deployments, list deployments, stream deploy logs, and watch rollouts in real time.

Every command outputs structured data (JSON or Rich tables) that you can pipe into other tools or inspect directly.

## Setup

### Install sgpctl

**Homebrew (macOS):**

```bash theme={null}
brew tap scaleapi/sgpctl https://github.com/scaleapi/sgpctl
brew install sgpctl
```

**Binary download (Linux/Windows):**

Download the latest binary for your platform from the [sgpctl GitHub releases](https://github.com/scaleapi/sgpctl/releases/latest).

**From the SGP monorepo:**

If you have the SGP repository cloned locally, you can build and install from source:

```bash theme={null}
cd services/sgpctl && poetry build && pipx install --force dist/sgpctl-*.whl
```

### Configure environment variables

All `sgpctl agentex-cloud` commands require three environment variables:

```bash theme={null}
export SGP_API_KEY="your-api-key"
export SGP_ACCOUNT_ID="your-account-id"
export SGP_BASE_URL="https://api.your-sgp-instance.scale.com"
```

<Note>
  All three environment variables are required. Commands will fail immediately if any of them is missing.
</Note>

You can add these exports to your shell profile (`~/.bashrc`, `~/.zshrc`) or load them from a `.env` file in your CI pipeline.

## Build commands

Build commands live under `sgpctl agentex-cloud build`. They let you submit new image builds, query build status, stream logs, and cancel running builds.

### Submit a build

Package your agent source code and submit it for a cloud build:

```bash theme={null}
sgpctl agentex-cloud build submit \
  --manifest ./manifest.yaml \
  --image-name my-agent \
  --tag v1.2.0
```

The `submit` command reads your `manifest.yaml`, packages the build context using `prepare_cloud_build_context()`, uploads the resulting tar.gz archive, and creates a build via `POST /v5/builds`.

On success, the command prints the build details as JSON:

```json theme={null}
{
  "build_id": "8f3a2c91-e4b7-4d2a-9f1c-3b5e7a8d6c02",
  "agent_name": "my-agent",
  "status": "queued",
  "image_name": "my-agent",
  "image_tag": "v1.2.0"
}
```

**Options:**

| Flag                 | Description                                             |
| -------------------- | ------------------------------------------------------- |
| `--manifest`, `-m`   | Path to `manifest.yaml` (required)                      |
| `--image-name`, `-i` | Repository name for the built image (required)          |
| `--tag`, `-t`        | Image tag (default: `latest`)                           |
| `--agent-name`, `-n` | Agent name override (inferred from manifest if omitted) |
| `--build-arg`, `-b`  | Build argument as `KEY=VALUE` (repeatable)              |
| `--platform`, `-p`   | Target platform (e.g. `linux/amd64`)                    |

You can pass multiple build arguments by repeating the flag:

```bash theme={null}
sgpctl agentex-cloud build submit \
  --manifest ./manifest.yaml \
  --image-name my-agent \
  --tag v1.2.0 \
  --build-arg PYTHON_VERSION=3.11 \
  --build-arg INSTALL_DEV_DEPS=false
```

### Get build details

Retrieve the full details of a specific build:

```bash theme={null}
sgpctl agentex-cloud build get 8f3a2c91-e4b7-4d2a-9f1c-3b5e7a8d6c02
```

Returns the build object as JSON, including status, image URL, timestamps, and associated metadata.

### List builds

List recent builds, optionally filtered by agent name:

```bash theme={null}
sgpctl agentex-cloud build list --agent-name my-agent --limit 10
```

Example output:

| Build ID                               | Agent Name | Build Status | Image Name | Image Tag | Image URL                | Created At          |
| -------------------------------------- | ---------- | ------------ | ---------- | --------- | ------------------------ | ------------------- |
| `8f3a2c91-e4b7-4d2a-9f1c-3b5e7a8d6c02` | my-agent   | success      | my-agent   | v1.2.0    | registry.sgp.scale.com/… | 2026-05-20 14:32:10 |
| `6d1b4e82-f3a9-4c8b-a2e5-9d7f1b3c8a04` | my-agent   | success      | my-agent   | v1.1.0    | registry.sgp.scale.com/… | 2026-05-18 09:15:43 |
| `2c7f9a31-d5e8-4a1f-b6c3-8e2d4f7a9b01` | my-agent   | failed       | my-agent   | v1.0.1    |                          | 2026-05-17 16:22:05 |

**Options:**

| Flag                 | Description                             |
| -------------------- | --------------------------------------- |
| `--agent-name`, `-n` | Filter by agent name                    |
| `--limit`, `-l`      | Maximum number of results (default: 20) |
| `--sort-order`       | Sort direction: `asc` or `desc`         |

### Stream build logs

Stream real-time build logs for a running or completed build:

```bash theme={null}
sgpctl agentex-cloud build logs 8f3a2c91-e4b7-4d2a-9f1c-3b5e7a8d6c02
```

Logs are delivered via Server-Sent Events (SSE) and print to stdout as they arrive:

```
[2026-05-20 14:32:15] Step 1/8 : FROM python:3.11-slim
[2026-05-20 14:32:16] ---> Using cache
[2026-05-20 14:32:16] Step 2/8 : WORKDIR /app
[2026-05-20 14:32:17] Step 3/8 : COPY requirements.txt .
[2026-05-20 14:32:18] Step 4/8 : RUN pip install -r requirements.txt
[2026-05-20 14:32:45] Step 5/8 : COPY . .
[2026-05-20 14:32:46] Step 6/8 : RUN python -m compileall .
[2026-05-20 14:32:48] Step 7/8 : EXPOSE 8080
[2026-05-20 14:32:48] Step 8/8 : CMD ["python", "main.py"]
[2026-05-20 14:32:50] Successfully built a1b2c3d4e5f6
[2026-05-20 14:32:52] Successfully tagged registry.sgp.scale.com/my-agent:v1.2.0
```

The command exits when the build completes or the timeout is reached.

| Flag        | Description                                     |
| ----------- | ----------------------------------------------- |
| `--timeout` | Maximum seconds to wait for logs (default: 300) |

### Cancel a build

Cancel a build that is queued or running:

```bash theme={null}
sgpctl agentex-cloud build cancel 8f3a2c91-e4b7-4d2a-9f1c-3b5e7a8d6c02
```

The build transitions to `cancelled` status. Builds that have already completed cannot be cancelled.

## Deploy commands

Deploy commands live under `sgpctl agentex-cloud deploy`. They let you submit deployments, check deployment status, stream logs, and watch rollouts.

### Submit a deployment

Deploy an agent using a completed build:

```bash theme={null}
sgpctl agentex-cloud deploy submit \
  --agent-path ./my-agent \
  --env production \
  --build-id 8f3a2c91-e4b7-4d2a-9f1c-3b5e7a8d6c02
```

The `submit` command reads `manifest.yaml` and `environments.yaml` from the directory specified by `--agent-path`, then creates a deployment via `POST /v5/agentex/deployments`.

Alternatively, specify an image directly instead of a build ID:

```bash theme={null}
sgpctl agentex-cloud deploy submit \
  --agent-path ./my-agent \
  --env staging \
  --image-name my-agent \
  --tag v1.2.0
```

**Options:**

| Flag                 | Description                                                                           |
| -------------------- | ------------------------------------------------------------------------------------- |
| `--agent-path`, `-a` | Path to agent directory containing `manifest.yaml` and `environments.yaml` (required) |
| `--env`, `-e`        | Environment key from `environments.yaml` (required)                                   |
| `--build-id`, `-b`   | Build ID to deploy                                                                    |
| `--image-name`, `-i` | Image repository name (alternative to `--build-id`)                                   |
| `--tag`, `-t`        | Image tag (used with `--image-name`)                                                  |
| `--watch`, `-w`      | Enter the live TUI dashboard after submitting                                         |

<Note>
  You must provide either `--build-id` or both `--image-name` and `--tag`. The command will reject the request if neither or both are specified.
</Note>

### Watch a deployment roll out

Pass `--watch` to `deploy submit` to enter a fullscreen Rich dashboard immediately after the deployment is created:

```bash theme={null}
sgpctl agentex-cloud deploy submit \
  --agent-path ./my-agent \
  --env production \
  --build-id 8f3a2c91-e4b7-4d2a-9f1c-3b5e7a8d6c02 \
  --watch
```

The TUI dashboard shows three sections: a status header at the top (agent name, environment, deployment ID, current status), a Kubernetes events panel on the left, and a container logs panel on the right. Both panels update in real time as the deployment progresses.

The dashboard auto-refreshes and exits automatically when the deployment reaches a terminal state (`healthy` or `failed`). Press `q` or `Ctrl+C` to exit early.

### Get deployment details

Retrieve the full details and events for a specific deployment:

```bash theme={null}
sgpctl agentex-cloud deploy get 4a9c1b72-e3f8-4d5a-8c2b-1f6e9d3a7b05
```

Returns the deployment object as JSON, including status, events timeline, and configuration.

### List deployments

List recent deployments:

```bash theme={null}
sgpctl agentex-cloud deploy list --limit 10
```

Example output:

| ID                                     | Agent       | Status  | Namespace      | Created At          |
| -------------------------------------- | ----------- | ------- | -------------- | ------------------- |
| `4a9c1b72-e3f8-4d5a-8c2b-1f6e9d3a7b05` | my-agent    | healthy | prod-agents    | 2026-05-20 14:33:00 |
| `9e2d5f81-a3c7-4b9e-d1f4-6c8a2e5b7d03` | my-agent    | healthy | staging-agents | 2026-05-19 11:20:15 |
| `1b8c3a62-f4d9-4e7c-a5b8-3d9f2c6e1a08` | support-bot | failed  | prod-agents    | 2026-05-19 09:45:33 |

**Options:**

| Flag            | Description                             |
| --------------- | --------------------------------------- |
| `--limit`, `-l` | Maximum number of results (default: 20) |

## Streaming logs

Both build and deploy commands support log streaming, but they use different transport mechanisms.

### Build logs (SSE)

Build logs stream via Server-Sent Events. The `build logs` command opens a persistent connection and prints each log line as it arrives:

```bash theme={null}
sgpctl agentex-cloud build logs 8f3a2c91-e4b7-4d2a-9f1c-3b5e7a8d6c02 --timeout 600
```

The connection closes when the build completes or the timeout expires. This is useful for watching a build in progress from your terminal.

### Deploy logs (cursor-paged polling)

Deploy logs use cursor-based polling. The `deploy logs` command fetches new log lines at a configurable interval:

```bash theme={null}
sgpctl agentex-cloud deploy logs 4a9c1b72-e3f8-4d5a-8c2b-1f6e9d3a7b05
```

By default, the output renders in a Rich Live TUI panel that updates in place. For CI environments or piping to a file, use the `--plain` flag:

```bash theme={null}
sgpctl agentex-cloud deploy logs 4a9c1b72-e3f8-4d5a-8c2b-1f6e9d3a7b05 --plain
```

In plain mode, each log line is written to stdout as a single line with no formatting, making it suitable for CI log capture or `grep`:

```
2026-05-20T14:33:24Z Starting application...
2026-05-20T14:33:25Z Loading model weights...
2026-05-20T14:33:28Z Model loaded in 3.2s
2026-05-20T14:33:28Z Health check endpoint ready
2026-05-20T14:33:28Z Listening on 0.0.0.0:8080
```

**Options:**

| Flag              | Description                                    |
| ----------------- | ---------------------------------------------- |
| `--poll-interval` | Seconds between log fetches (default: 2)       |
| `--plain`         | Plain text output, no TUI (recommended for CI) |

## Common workflows

### Ship from laptop

Build an image and deploy it in one sequence:

```bash theme={null}
# Submit the build
sgpctl agentex-cloud build submit \
  --manifest ./manifest.yaml \
  --image-name my-agent \
  --tag v1.2.0

# Stream logs until the build completes
sgpctl agentex-cloud build logs 8f3a2c91-e4b7-4d2a-9f1c-3b5e7a8d6c02 --timeout 600

# Deploy and watch the rollout
sgpctl agentex-cloud deploy submit \
  --agent-path ./my-agent \
  --env production \
  --build-id 8f3a2c91-e4b7-4d2a-9f1c-3b5e7a8d6c02 \
  --watch
```

After the build completes, the deploy command with `--watch` gives you a live view of the rollout from start to finish.

### Check what is deployed

List active deployments to see which builds are currently serving traffic:

```bash theme={null}
sgpctl agentex-cloud deploy list
```

To get full details on a specific deployment, including the image tag and environment configuration:

```bash theme={null}
sgpctl agentex-cloud deploy get 4a9c1b72-e3f8-4d5a-8c2b-1f6e9d3a7b05
```

### Roll back to a previous build

Redeploy a known-good build by referencing its build ID:

```bash theme={null}
sgpctl agentex-cloud deploy submit \
  --agent-path ./my-agent \
  --env production \
  --build-id 6d1b4e82-f3a9-4c8b-a2e5-9d7f1b3c8a04 \
  --watch
```

This creates a new deployment using the image from the previous build. The existing deployment is replaced when the new one becomes healthy.

### Tail logs on a running deployment

Stream container logs from a deployment that is already running:

```bash theme={null}
sgpctl agentex-cloud deploy logs 4a9c1b72-e3f8-4d5a-8c2b-1f6e9d3a7b05
```

Use `--plain` to capture logs in a file:

```bash theme={null}
sgpctl agentex-cloud deploy logs 4a9c1b72-e3f8-4d5a-8c2b-1f6e9d3a7b05 --plain > deploy.log
```

## Next steps

* [API and SDK](/docs/v5/agents/agentex/cloud-build-and-deploy/api): programmatic access to builds and deployments
* [CI/CD with Gitea Actions](/docs/v5/agents/agentex/cloud-build-and-deploy/ci-cd): automate builds triggered by git push
* [Secrets](/docs/v5/agents/agentex/cloud-build-and-deploy/secrets): store and reference credentials used during builds and deployments