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

# 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