feat: update CLI command reference

cli/basic-usage.mdx

@@ -2,59 +2,191 @@
 title: "Basic Usage"
 ---
 
-To set up and authenticate with the CLI, run the following command:
-
-```
-porter auth login
+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
+    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
+    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
+    porter apply -f porter.yaml
+    ```
+
+    [porter.yaml reference](/deploy/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
+porter projects list
 ```
 
-This command will automatically set a project ID and a cluster ID in your default configuration file, if you have a project and cluster. You can always view your default configuration by running `porter config`. You can see all projects that you have access to by running:
+### Set Active Project
 
-```
-porter projects list
+```bash
+porter config set-project [PROJECT_ID]
 ```
 
-And you can set a project via:
+### List Available Clusters
 
-```
-porter config set-project [PROJECT_ID]
+```bash
+porter clusters list
 ```
 
-Next, you can see all clusters that you have access to via:
+### Set Active Cluster
 
+```bash
+porter config set-cluster [CLUSTER_ID]
 ```
-porter clusters list
+
+### View Current Configuration
+
+```bash
+porter config
 ```
 
-And similarly, you can set the cluster:
+## 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
+porter app logs my-app --project 12345
 ```
-porter config set-cluster [CLUSTER_ID]
+
+```bash Override Cluster
+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>
 
-## Environment Variables and Global Flags[](#environment-variables-and-global-flags "Direct link to heading")
+### Example: CI/CD Configuration
 
-The following environment variables can be set in order to authenticate to and target a specific Porter project or cluster:
+```bash
+export PORTER_TOKEN="your-deploy-token"
+export PORTER_PROJECT="12345"
+export PORTER_CLUSTER="67890"
 
+porter apply -f porter.yaml
 ```
-PORTER_PROJECT
-PORTER_CLUSTER
-PORTER_TOKEN
+
+## Common Workflows
+
+### Local Development
+
+```bash
+# 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
 ```
 
-These are also supported as global flags:
+### CI/CD Deployment
 
+```bash
+# Deploy with explicit configuration
+PORTER_TOKEN=$DEPLOY_TOKEN \
+PORTER_PROJECT=$PROJECT_ID \
+PORTER_CLUSTER=$CLUSTER_ID \
+porter apply -f porter.yaml
 ```
---cluster uint   cluster ID of Porter cluster
---project uint   project ID of Porter project
---token string   token for Porter authentication
+
+### Managing Environment Variables
+
+```bash
+# 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
 ```
 
-## Viewing Help Instructions[](#viewing-help-instructions "Direct link to heading")
+### Debugging
+
+```bash
+# Stream live logs
+porter app logs my-app
 
-You can view help instructions for any command via the `-h`, or `--help` flag. For example:
+# View historical logs
+porter app logs my-app --since 1h
 
+# Run a command in an ephemeral copy of your app
+porter app run my-app -- bash
 ```
+
+## Viewing Help
+
+You can view help instructions for any command using the `-h` or `--help` flag:
+
+```bash
+# General help
 porter -h
-porter cluster -h
-```
+
+# Help for a specific command
+porter app -h
+
+# Help for a subcommand
+porter app run -h
+```
+
+## Next Steps
+
+- Learn about [configuration-as-code](/deploy/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](/deploy/using-other-ci-tools) for automated deployments

cli/installation.mdx

@@ -8,30 +8,29 @@ To install the Porter CLI, see the OS-specific instructions below.
 
 The installation process depends on the `curl` and `unzip` utilities.
 
-- Mac
-- Linux
-- Windows
-
-#### Install via Homebrew[](#install-via-homebrew "Direct link to heading")
-
-```
-brew install porter-dev/porter/porter
-```
-
-#### Manual Installation[](#manual-installation "Direct link to heading")
-
-```
-/bin/bash -c "$(curl -fsSL https://install.porter.run)"
-```
+<Tabs>
+  <Tab title="Mac">
+    #### Install via Homebrew
+
+    ```bash
+    brew install porter-dev/porter/porter
+    ```
+
+    #### Manual Installation
+
+    ```bash
+    /bin/bash -c "$(curl -fsSL https://install.porter.run)"
+    ```
+  </Tab>
+  <Tab title="Linux">
+    ```bash
+    /bin/bash -c "$(curl -fsSL https://install.porter.run)"
+    ```
+  </Tab>
+</Tabs>
 
 After installing, run the following to verify your installation:
 
-```
+```bash
 porter version
 ```
-
-To authenticate the CLI, run:
-
-```
-porter auth login
-```