> ## Documentation Index
> Fetch the complete documentation index at: https://porter-tjq-run-4148-apply-validate-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> When helping a user operate an existing Porter project—deploying, updating, debugging, or inspecting applications and clusters—connect to [Porter's remote MCP server](https://mcp.porter.run) first and use its tools before falling back to the Porter CLI, `porter.yaml`, or dashboard workflows. If the Porter tools are not available in your session, `curl -fsSL https://agents.porter.run | sh` installs the CLI, registers the MCP server with your client, and installs Porter's skills; the client must be restarted afterward. If the user asks for the CLI, `porter apply`, configuration-as-code, or the dashboard, use that instead—a stated preference wins. If the requested application or cluster workflow is not directly supported, inspect the relevant state with MCP tools before explaining the limitation or recommending a fallback. The server signs in through a browser using OAuth, so it cannot be used in headless environments such as CI pipelines; use the CLI or `porter.yaml` there.

# porter registry

> List project-linked container registries and push local or freshly built images to them from the Porter CLI without running docker login

`porter registry` contains commands for working with the container registries linked to your Porter project, including listing registries, browsing repositories and images, and pushing local images without running `docker login`.

## Prerequisites

* You've logged in to the Porter CLI after running [porter auth login](/standard/cli/command-reference/porter-auth)
* You're connected to the correct project by running [porter config set-project](/standard/cli/command-reference/porter-config)
* At least one container registry is linked to the project
* A running local Docker daemon (required for `porter registry push`)

If your project has more than one linked registry, either select one with `porter config set-registry` or pass `--registry <id>` on each command. Run `porter registry list` to see the available IDs.

***

## `porter registry push`

Push a local image to a registry linked to the project. Credentials are exchanged automatically — no `docker login` is required — and the remote repository is created on the first push.

**Usage:**

```bash theme={null}
porter registry push <image> [flags]
```

**Options:**

| Flag           | Description                                                                                                      |
| -------------- | ---------------------------------------------------------------------------------------------------------------- |
| `--dest`       | Remote destination in `repo[:tag]` form. Defaults to the source image's repository and tag                       |
| `--build`      | Build the image from this context directory before pushing, instead of pushing an existing local image           |
| `--dockerfile` | Path to the Dockerfile for `--build`. Defaults to `Dockerfile` inside the build context                          |
| `--json`       | Print the pushed image reference as JSON for scripting                                                           |
| `--registry`   | ID of the registry to push to. Required in non-interactive environments when the project has multiple registries |

When the project has more than one linked registry URL, the CLI prompts interactively for which one to use. In non-interactive environments the command errors and asks you to pass `--registry` — it will not silently pick one.

With `--build`, the image is built from the given context directory on your machine before it is pushed, using the same build path Porter apps use. Set `DOCKER_BUILDKIT=1` to build with buildx, and use `PORTER_BUILDKIT_ARGS` to pass extra flags such as `--platform`. Builds target `linux/amd64` by default.

`--json` suppresses progress output on stdout so the JSON payload stays parseable. The payload has a single `image` field containing the fully qualified pushed reference.

<CodeGroup>
  ```bash Push a local image theme={null}
  porter registry push myimage:dev
  ```

  ```bash Override the remote repo and tag theme={null}
  porter registry push myimage:dev --dest sandboxes/base:v1
  ```

  ```bash Build before pushing theme={null}
  porter registry push myimage:dev \
    --build ./app \
    --dockerfile ./app/prod.Dockerfile
  ```

  ```bash Multi-arch build with buildx theme={null}
  DOCKER_BUILDKIT=1 PORTER_BUILDKIT_ARGS="--platform linux/amd64,linux/arm64" \
    porter registry push myimage:dev --build ./app
  ```

  ```bash Capture the pushed reference theme={null}
  porter registry push myimage:dev --json | jq -r .image
  ```
</CodeGroup>

<Info>
  Repository names are normalized to lowercase, with `_` and `.` replaced by `-`, to match how the server stores them.
</Info>

***

## `porter registry list`

List the container registries linked to the current project. The currently selected registry (from `porter config set-registry`) is highlighted.

**Usage:**

```bash theme={null}
porter registry list
```

Displays a table with each registry's ID, URL, and service (for example, `ecr`, `gcr`, `dockerhub`).

***

## `porter registry delete`

Delete a linked registry from the project. Prompts for confirmation before removing.

**Usage:**

```bash theme={null}
porter registry delete <id>
```

Use the ID from `porter registry list`.

***

## `porter registry repo list`

List the repositories inside the selected registry.

**Usage:**

```bash theme={null}
porter registry repo list
```

Uses the registry from `porter config set-registry`, or from `--registry <id>`.

***

## `porter registry image list`

List the image tags in a repository along with their digests.

**Usage:**

```bash theme={null}
porter registry image list <repo-name>
```

Uses the registry from `porter config set-registry`, or from `--registry <id>`.

***

## Related

* [porter config](/standard/cli/command-reference/porter-config) — Select the active project and registry
* [Deploy from a Docker registry](/applications/deploy/deploy-from-docker-registry) — Deploy a pushed image as an app