> ## 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.

# CLI basic usage

> Authenticate, configure projects and clusters, and deploy applications using essential Porter CLI commands including apply, config, and app

This guide covers the essential commands and configuration options for the Porter CLI.

## Quick Start

<Steps>
  <Step title="Login to Porter">
    Authenticate with your Porter account:

    ```bash theme={null}
    porter auth login
    ```

    This opens your browser to complete authentication and automatically configures your default project and cluster.
  </Step>

  <Step title="Verify Configuration">
    Check your current CLI configuration:

    ```bash theme={null}
    porter config
    ```

    If necessary, [switch your project and/or cluster](#project-and-cluster-configuration)
  </Step>

  <Step title="Deploy Your App">
    Deploy using a `porter.yaml` file:

    ```bash theme={null}
    porter apply -f porter.yaml
    ```

    [`porter.yaml` reference](/applications/configuration-as-code/overview)

    [`porter apply` reference](/standard/cli/command-reference/porter-apply)
  </Step>
</Steps>

## Project and Cluster Configuration

After logging in, you may need to switch between projects or clusters.

### List Available Projects

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

### Set Active Project

```bash theme={null}
porter config set-project [PROJECT_ID]
```

### List Available Clusters

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

### Set Active Cluster

```bash theme={null}
porter config set-cluster [CLUSTER_ID]
```

### View Current Configuration

```bash theme={null}
porter config
```

## Global Flags

These flags can be used with any Porter command:

| Flag               | Description                              |
| ------------------ | ---------------------------------------- |
| `--project <id>`   | Override the project ID for this command |
| `--cluster <id>`   | Override the cluster ID for this command |
| `--token <string>` | Use a specific authentication token      |
| `-h, --help`       | Display help for the command             |

<CodeGroup>
  ```bash Override Project theme={null}
  porter app logs my-app --project 12345
  ```

  ```bash Override Cluster theme={null}
  porter app run my-app --cluster 67890 -- bash
  ```
</CodeGroup>

## Environment Variables

Environment variables provide an alternative way to configure the CLI, which is especially useful in CI/CD pipelines.

| Variable          | Description                   | Equivalent Flag |
| ----------------- | ----------------------------- | --------------- |
| `PORTER_PROJECT`  | Project ID to use             | `--project`     |
| `PORTER_CLUSTER`  | Cluster ID to use             | `--cluster`     |
| `PORTER_TOKEN`    | Authentication token          | `--token`       |
| `PORTER_HOST`     | Custom Porter API host        | `--host`        |
| `PORTER_APP_NAME` | Default app name for commands | `--app`         |

<Info>
  Environment variables take precedence over values in your config file, but flags take precedence over environment variables.
</Info>

### Example: CI/CD Configuration

```bash theme={null}
export PORTER_TOKEN="your-deploy-token"
export PORTER_PROJECT="12345"
export PORTER_CLUSTER="67890"

porter apply -f porter.yaml
```

## Common Workflows

### Local Development

```bash theme={null}
# Login and configure
porter auth login

# View your app's logs
porter app logs my-app

# Run a command in an ephemeral copy of your app
porter app run my-app -- bash

# View current app configuration
porter app yaml my-app
```

### CI/CD Deployment

```bash theme={null}
# Deploy with explicit configuration
PORTER_TOKEN=$DEPLOY_TOKEN \
PORTER_PROJECT=$PROJECT_ID \
PORTER_CLUSTER=$CLUSTER_ID \
porter apply -f porter.yaml
```

### Managing Environment Variables

```bash theme={null}
# Pull environment variables from an app
porter env pull -a my-app

# Pull environment variables from an environment group
porter env pull -g my-env-group

# Set environment variables on an app
porter env set -a my-app -v KEY=value

# Set secrets on an environment group
porter env set -g my-env-group -s API_KEY=secret123
```

### Debugging

```bash theme={null}
# Stream live logs
porter app logs my-app

# View historical logs
porter app logs my-app --since 1h
```

## Viewing Help

You can view help instructions for any command using the `-h` or `--help` flag:

```bash theme={null}
# General help
porter -h

# Help for a specific command
porter app -h

# Help for a subcommand
porter app run -h
```

## Next Steps

* Learn about [configuration-as-code](/applications/configuration-as-code/overview) with `porter.yaml`
* Explore the [full command reference](/standard/cli/command-reference/porter-apply) for detailed options
* Set up [CI/CD deployment](/applications/deploy/using-other-ci-tools) for automated deployments