diff --git a/cli/basic-usage.mdx b/cli/basic-usage.mdx index c4e0be0..fefcabb 100644 --- a/cli/basic-usage.mdx +++ b/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 + + + + Authenticate with your Porter account: + ```bash + porter auth login + ``` + This opens your browser to complete authentication and automatically configures your default project and cluster. + + + Check your current CLI configuration: + ```bash + porter config + ``` + If necessary, [switch your project and/or cluster](#project-and-cluster-configuration) + + + 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) + + + +## 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 ` | Override the project ID for this command | +| `--cluster ` | Override the cluster ID for this command | +| `--token ` | Use a specific authentication token | +| `-h, --help` | Display help for the command | + + +```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 ``` + + +## 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` | + + +Environment variables take precedence over values in your config file, but flags take precedence over environment variables. + -## 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 -``` \ No newline at end of file + +# 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 diff --git a/cli/installation.mdx b/cli/installation.mdx index 3fbd4c5..2b69ac2 100644 --- a/cli/installation.mdx +++ b/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)" -``` + + + #### Install via Homebrew + + ```bash + brew install porter-dev/porter/porter + ``` + + #### Manual Installation + + ```bash + /bin/bash -c "$(curl -fsSL https://install.porter.run)" + ``` + + + ```bash + /bin/bash -c "$(curl -fsSL https://install.porter.run)" + ``` + + After installing, run the following to verify your installation: -``` +```bash porter version ``` - -To authenticate the CLI, run: - -``` -porter auth login -``` diff --git a/cli/v1-and-v2.mdx b/cli/v1-and-v2.mdx deleted file mode 100644 index 057fa17..0000000 --- a/cli/v1-and-v2.mdx +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: "v1 and v2" ---- - -There are two versions of the CLI that are currently supported by Porter. All projects that were created after May 1st, 2023 will be using the v2 CLI. All projects created before then will be using the v1 CLI. - -We will be deprecating the v1 CLI on June 30th, 2024. For all our existing users, you will receive an email from us to ensure that this deprecation will not cause any disruption in your current Porter setup before the deprecation date. - -Please consult the appropriate command reference depending on the CLI version you are using. \ No newline at end of file diff --git a/standard/cli/command-reference/porter-app.mdx b/standard/cli/command-reference/porter-app.mdx index bdb486b..9f3952c 100644 --- a/standard/cli/command-reference/porter-app.mdx +++ b/standard/cli/command-reference/porter-app.mdx @@ -2,157 +2,274 @@ title: 'porter app' --- -##### Prerequisites +`porter app` contains commands for managing and interacting with your applications. -- You've logged in to the Porter CLI after running [porter auth login](/enterprise/cli/command-reference/porter-auth) -- You're connected to the correct project by running [porter config set-project](/enterprise/cli/command-reference/porter-config) -- You're connected to the correct cluster by running [porter config set-cluster](/enterprise/cli/command-reference/porter-config) +## Prerequisites -### `porter app run`[](#porter-run 'Direct link to heading') +- 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) +- You're connected to the correct cluster by running [porter config set-cluster](/standard/cli/command-reference/porter-config) -The `porter app run` command allows users to execute a command on a remote container: +--- -``` -porter app run [APP_NAME] -- [COMMAND] [args...] +## `porter app run` + +Execute a command in your application's container. By default, this spins up an ephemeral copy of your container that is deleted when the command completes. + +**Usage:** +```bash +porter app run [APP_NAME] [flags] -- [COMMAND] [args...] ``` -The `APP_NAME` is the name of the application on the Porter dashboard. +**Options:** -Running `porter app run` spins up an ephemeral copy of your application -container. This container will be deleted when your command completes, -or when you exit your interactive shell session. +| Flag | Short | Description | +|------|-------|-------------| +| `--existing` | `-e` | Connect to an existing running container instead of spinning up a new one | +| `--job` | | Trigger a manual run of the specified job | +| `--wait` | | Wait for the job to complete before exiting (used with `--job`) | +| `--allow-concurrent` | | Allow concurrent runs for jobs that normally restrict it | +| `--service` | | Specify which service to connect to | -To connect to an existing running container, you can specify the `-e` flag: + +```bash Interactive Shell +porter app run my-app -- bash +``` +```bash Existing Container +porter app run -e my-app -- bash ``` -porter app run -e [APP_NAME] -- [COMMAND] [args...] + +```bash Trigger Job +porter app run my-app --job my-job ``` -**Common Usage** [](#porter-run-examples 'Direct link to heading') +```bash Wait for Job +porter app run my-app --job my-job --wait +``` +```bash Concurrent Job +porter app run my-app --job my-job --allow-concurrent ``` -porter app run [APP_NAME] -- bash + +```bash Run Command +porter app run my-app -- python manage.py migrate ``` + + + +If `bash` isn't available in your container, try `sh` for a similar interactive experience. + -This will launch an interactive shell session through which you can run other commands, like `ls`, `ps`, etc. If `bash` isn't found on your container, you can also try `sh` for a similar result. +--- -**Running Jobs** [](#porter-run-job-examples 'Direct link to heading') +## `porter app logs` -You can also use this command to trigger manual job runs for existing jobs in your application using the `--job` flag. +Stream real-time logs or view historical logs from your application. +**Usage:** +```bash +porter app logs [APP_NAME] [flags] ``` -porter app run [APP_NAME] --job [JOB_NAME] + +**Options:** + +| Flag | Description | +|------|-------------| +| `--service` | Filter logs by service name | +| `--search` | Search for a specific string in the logs | +| `--revision` | Stream logs from a specific revision | + +**Historical Log Options:** + +| Flag | Description | +|------|-------------| +| `--since` | Pull logs from the specified duration (e.g., `12h`, `30m`) | +| `--from` | Start timestamp for historical logs (RFC3339 format) | +| `--to` | End timestamp for historical logs (RFC3339 format) | +| `--limit` | Number of lines to return (default: 100) | +| `--newest-first` | Return newest logs first (default: true) | + + +```bash Stream Live Logs +porter app logs my-app ``` -You can wait for the job to complete before exiting using the `--wait` flag: +```bash Filter by Service +porter app logs my-app --service web +``` +```bash Search Logs +porter app logs my-app --search "error" ``` -porter app run [APP_NAME] --job [JOB_NAME] --wait + +```bash Historical Logs +porter app logs my-app --since 12h ``` -For jobs that do not allow concurrent runs, you can override this behavior using the `--allow-concurrent` flag: +```bash Time Range +porter app logs my-app --from 2025-01-15T10:00:00Z --to 2025-01-15T12:00:00Z +``` +```bash Limit Results +porter app logs my-app --since 24h --limit 500 ``` -porter app run [APP_NAME] --job [JOB_NAME] --allow-concurrent + + + +By default, the command streams new logs. Setting `--since` or `--from`/`--to` switches to pulling historical logs. + + +--- + +## `porter app build` + +Build a new container image for an app based on its existing build settings. Any build setting can be overridden with flags. + +**Usage:** +```bash +porter app build [APP_NAME] [flags] ``` -### `porter app logs`[](#porter-logs 'Direct link to heading') +**Options:** + +| Flag | Description | +|------|-------------| +| `--build-context` | Override the build context directory | +| `--dockerfile` | Override the Dockerfile path | +| `--tag` | Specify a custom image tag | +| `--method` | Build method (`docker` or `pack`) | +| `--builder` | Builder image for buildpack builds | +| `--buildpacks` | Comma-separated list of buildpacks | -The `porter app logs` command allows users to stream new logs or view historical logs from their application: + +```bash Basic Build +porter app build my-app +``` +```bash Custom Context +porter app build my-app --build-context ./frontend --dockerfile ./frontend/Dockerfile ``` -porter app logs [APP_NAME] + +```bash With Tag +porter app build my-app --tag v1.2.3 ``` + -The following flags can be used to filter the logs: +--- -```yaml -# --service: -# filter logs by service name -porter app logs [APP_NAME] --service [SERVICE_NAME] +## `porter app push` -# --search: -# search for a specific string in the logs -porter app logs [APP_NAME] --search [SEARCH_STRING] +Push a container image to the default registry for the app. Can be used with `porter app build` to build and push as discrete steps. -# --revision: -# stream logs from a specific revision -porter app logs [APP_NAME] --revision=[REVISION_NUMBER] +**Usage:** +```bash +porter app push [APP_NAME] [flags] ``` -By default, the command will stream new logs. Setting the `--since` flag or the `--from --to` flags will switch to pulling historical logs: +**Options:** -```yaml -# --since: -# pull logs over the specified duration -# looking back from the current time -porter app logs [APP_NAME] --since 12h +| Flag | Description | +|------|-------------| +| `--tag` | Specify the image tag to push (defaults to current branch HEAD) | -# --from and --to: -# pull logs between the specified timestamps -porter app logs [APP_NAME] --from 2021-01-01T10:00:00Z --to 2021-01-01T12:00:00Z + +```bash Push Latest +porter app push my-app +``` -# with timezone: -porter app logs [APP_NAME] --from 2021-01-01T06:00:00-04:00 --to 2021-01-01T08:00:00-04:00 +```bash Push Specific Tag +porter app push my-app --tag v1.2.3 ``` + +--- -When viewing historical logs, these additional flags can be used: +## `porter app update` -```yaml -# --limit: -# the number of lines of historical logs to return -# defaults to 100 -porter app logs [APP_NAME] --since 12h --limit=[LIMIT] +Update an application with the provided configuration without building a new image. This is similar to updating the app in the Porter dashboard. -# --newest-first: -# return the newest historical logs first -# defaults to true -porter app logs [APP_NAME] --since 12h --newest-first=false +**Usage:** +```bash +porter app update [APP_NAME] [flags] ``` -### `porter app build`[](#porter-build 'Direct link to heading') - -The `porter app build` command builds a new container image for an app based on it's existing build settings. Any build setting can be overridden with a corresponding flag. +**Options:** -For example, to start a Docker build for an app in the `./frontend` directory, you can run: +| Flag | Short | Description | +|------|-------|-------------| +| `--file` | `-f` | Path to the `porter.yaml` configuration file | +| `--tag` | | Update the image tag | + +```bash Update from YAML +porter app update my-app -f porter.yaml ``` -porter app build [APP_NAME] --build-context ./frontend --dockerfile ./frontend/Dockerfile + +```bash Update Image Tag +porter app update my-app --tag v1.2.3 ``` + -### `porter app push`[](#porter-push 'Direct link to heading') + +This command differs from `porter apply` in that it only updates the app configuration without attempting to build a new image. + -The `porter app push` command pushes a container image to the default registry for the app. This command can be used with the `app build` command to build and push an image as discrete steps. +--- -The `--tag` flag can be used to specify the image tag to push. Otherwise, the head of the current branch will be used as the tag. +## `porter app update-tag` -``` -porter app push [APP_NAME] --tag [TAG] +Update the image tag for an application. This is functionally equivalent to running `porter apply` or `porter app update` with the `--tag` flag. + +**Usage:** +```bash +porter app update-tag [APP_NAME] [flags] ``` -### `porter app update`[](#porter-update 'Direct link to heading') +**Options:** -The `porter app update` command updates the specified app with the provided configuration. This command differs from "porter apply" in that it only updates the app, but does not attempt to build a new image. This is similar to updating the app in the Porter dashboard. +| Flag | Description | +|------|-------------| +| `--tag` | The new image tag to deploy (required) | +```bash +porter app update-tag my-app --tag abc123def ``` -porter app update [APP_NAME] -f porter.yaml -``` -### `porter app update-tag`[](#porter-update-tag 'Direct link to heading') +--- + +## `porter app yaml` -`porter app update-tag` updates the image of the specified application with the tag provided by the `--tag` flag. For example: +Export the current Porter YAML configuration for an application. Useful for bootstrapping a `porter.yaml` file or inspecting the current configuration. +**Usage:** +```bash +porter app yaml [APP_NAME] ``` -porter app update-tag --tag + +```bash +porter app yaml my-app ``` -This command is functionally equivalent to running either `porter apply` or `porter app update` with the `--tag` flag. + +Redirect the output to create a `porter.yaml` file: `porter app yaml my-app > porter.yaml` + -### `porter app yaml`[](#porter-yaml 'Direct link to heading') +--- -`porter app yaml` returns the Porter YAML for the specified application. For example: +## `porter app list` +List all applications in the current project and cluster. + +**Usage:** +```bash +porter app list ``` -porter app yaml -``` + +--- + +## Related Commands + +- [porter apply](/standard/cli/command-reference/porter-apply) - Deploy an app using configuration-as-code +- [porter job](/standard/cli/command-reference/porter-job) - Manage jobs +- [porter env](/standard/cli/command-reference/porter-env) - Manage environment variables diff --git a/standard/cli/command-reference/porter-auth.mdx b/standard/cli/command-reference/porter-auth.mdx index d052f26..7ce68e1 100644 --- a/standard/cli/command-reference/porter-auth.mdx +++ b/standard/cli/command-reference/porter-auth.mdx @@ -1,25 +1,56 @@ --- -title: "porter auth" +title: 'porter auth' --- -`porter auth` contains commands for authenticating with a Porter instance. +`porter auth` contains commands for authenticating with Porter. -### `porter auth login`[](#porter-auth-login "Direct link to heading") +--- -Logs a user in to the Porter instance. This command will by default attempt to open your default browser to authenticate you. If this does not succeed, the command will output a URL to visit which will redirect you to the Porter instance. +## `porter auth login` -If you would like to log in via a cookie-based mechanism by inputting an email/password, run: +Authenticate with your Porter account. By default, this opens your browser to complete authentication. +**Usage:** +```bash +porter auth login [flags] ``` -porter auth login --manual -``` -If you would like to log in using a token that you can find by running `porter config`: +**Options:** + +| Flag | Description | +|------|-------------| +| `--manual` | Log in by entering email and password instead of browser auth | +| `--token` | Log in using an existing token | + +```bash Browser Login (Default) +porter auth login +``` + +```bash Manual Login +porter auth login --manual ``` -porter auth --token + +```bash Token Login +porter auth login --token ``` + + + +After logging in, Porter automatically sets your default project and cluster if you have access to any. You can view these with `porter config`. + + +--- -### `porter auth logout`[](#porter-auth-logout "Direct link to heading") +## `porter auth logout` + +Log out from Porter and clear your local credentials. + +**Usage:** +```bash +porter auth logout +``` -Logs a user out from a Porter instance. \ No newline at end of file + +After logging out, you'll need to run `porter auth login` again before using other commands. + diff --git a/standard/cli/command-reference/porter-cluster.mdx b/standard/cli/command-reference/porter-cluster.mdx index 88b27b2..64699bb 100644 --- a/standard/cli/command-reference/porter-cluster.mdx +++ b/standard/cli/command-reference/porter-cluster.mdx @@ -1,15 +1,32 @@ --- -title: "porter cluster" +title: 'porter cluster' --- -##### Prerequisites +`porter cluster` contains commands for viewing and managing clusters. -* You've logged in to the Porter CLI after running [porter auth login](/enterprise/cli/command-reference/porter-auth) -* You're connected to the correct project by running [porter config set-project](/enterprise/cli/command-reference/porter-config) +## Prerequisites - -`porter cluster` contains commands for reading from a connected cluster. +- 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) -### `porter cluster list`[](#porter-cluster-list "Direct link to heading") +--- + +## `porter cluster list` + +List all clusters in the current project. + +**Usage:** +```bash +porter cluster list +``` + + +Use `porter config set-cluster` to switch between clusters after listing them. + + +--- + +## Related Commands -This lists all clusters under a certain project. \ No newline at end of file +- [porter config set-cluster](/standard/cli/command-reference/porter-config) - Set the active cluster +- [porter project list](/standard/cli/command-reference/porter-project) - List available projects diff --git a/standard/cli/command-reference/porter-config.mdx b/standard/cli/command-reference/porter-config.mdx index daaa3c1..0088ef0 100644 --- a/standard/cli/command-reference/porter-config.mdx +++ b/standard/cli/command-reference/porter-config.mdx @@ -1,25 +1,98 @@ --- -title: "porter config" +title: 'porter config' --- -`porter config` contains commands for controlling local configuration settings. +`porter config` contains commands for managing local CLI configuration settings. -### `porter config`[](#porter-config "Direct link to heading") +--- + +## `porter config` + +Display the current CLI configuration, including project, cluster, and authentication details. + +**Usage:** +```bash +porter config +``` + + +Configuration values can be overridden using flags or environment variables. See [Basic Usage](/cli/basic-usage) for details. + -Running `porter config` with no subcommands will output the current configuration file to the terminal. Note that this configuration may be overwritten through a combination of flags and environment variables. +--- -### `porter config set-host [HOSTNAME]`[](#porter-config-set-host-hostname "Direct link to heading") +## `porter config set-host` -Saves the host in the default configuration. Note this host must include the protocol and should not contain trailing slashes. For example: +Saves the host in the default configuration. +**Usage:** +```bash +porter config set-host [HOSTNAME] ``` + +```bash porter config set-host https://dashboard.porter.run ``` -### `porter config set-project`[](#porter-config-set-project "Direct link to heading") + +The hostname must include the protocol (`https://`) and should not contain trailing slashes. + + +--- + +## `porter config set-project` + +Set the active project. This command shows a list of projects you have access to and lets you select one. + +**Usage:** +```bash +porter config set-project [PROJECT_ID] +``` + + +```bash Interactive Selection +porter config set-project +``` + +```bash Direct ID +porter config set-project 12345 +``` + + +--- + +## `porter config set-cluster` + +Set the active cluster. This command shows a list of clusters in the current project and lets you select one. + +**Usage:** +```bash +porter config set-cluster [CLUSTER_ID] +``` + + +```bash Interactive Selection +porter config set-cluster +``` + +```bash Direct ID +porter config set-cluster 67890 +``` + + + +Run `porter cluster list` first to see available clusters and their IDs. + + +--- -Saves the project ID in the default configuration from a list of projects that you have access to. +## Configuration File -### `porter config set-cluster`[](#porter-config-set-cluster "Direct link to heading") +Porter stores configuration in `~/.porter/config.json`. You can also override settings using environment variables: -Saves the cluster ID in the default configuration from a list of clusters that the current project has access to. \ No newline at end of file +| Variable | Description | +|----------|-------------| +| `PORTER_PROJECT` | Override project ID | +| `PORTER_CLUSTER` | Override cluster ID | +| `PORTER_TOKEN` | Override authentication token | +| `PORTER_HOST` | Override API host | diff --git a/standard/cli/command-reference/porter-datastore-connect.mdx b/standard/cli/command-reference/porter-datastore-connect.mdx index a47cb4c..10fd7fa 100644 --- a/standard/cli/command-reference/porter-datastore-connect.mdx +++ b/standard/cli/command-reference/porter-datastore-connect.mdx @@ -2,45 +2,66 @@ title: 'porter datastore connect' --- -##### Prerequisites +`porter datastore connect` creates a secure tunnel to connect to Porter-provisioned datastores from your local machine. -- You've logged in to the Porter CLI after running [porter auth login](/enterprise/cli/command-reference/porter-auth) -- You're connected to the correct project by running [porter config set-project](/enterprise/cli/command-reference/porter-config) -- You have used Porter to provision a datastore +## Prerequisites -## Datastores[](#applications 'Direct link to heading') +- 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) +- You have a Porter-provisioned datastore (PostgreSQL, Redis, etc.) -`porter datastore connect` creates a secure tunnel through which you can connect to your Porter-provisioned datastore locally. For example: +--- +## Usage + +```bash +porter datastore connect [flags] ``` -porter datastore connect -``` -Example output from running this command: +**Options:** + +| Flag | Description | +|------|-------------| +| `--port` | Local port for the tunnel (default: 8122) | +--- + +## Examples + + +```bash Connect to Datastore +porter datastore connect my-postgres ``` -Secure tunnel setup complete! While the tunnel is running, you can connect to your datastore using the following credentials: - Host: 127.0.0.1 - Port: 8122 - Database name: postgres - Password: - -Starting proxy...[CTRL-C to exit] -Forwarding from 127.0.0.1:8122 -> 6379 -Forwarding from [::1]:8122 -> 6379 -Handling connection for 8122 + +```bash Custom Port +porter datastore connect my-postgres --port 5433 ``` + -While the secure tunnel is running, you can run the following command in a separate shell to connect to your datastore (assuming the datastore is a redis cache): +--- + +## Connecting to Your Datastore +While the tunnel is running, connect using your preferred client in a separate terminal: + + +```bash PostgreSQL +psql -h 127.0.0.1 -p 8122 -U postgres -d postgres ``` + +```bash Redis redis-cli -p 8122 -a --tls ``` -### Port +```bash MySQL +mysql -h 127.0.0.1 -P 8122 -u root -p +``` + -If you would like to specify the port on which to connect to the secure tunnel, you can use the `--port` flag. By default, this is set to 8122. + +The tunnel stays open until you press `CTRL-C`. Keep the terminal open while you need access to the datastore. + -``` -porter datastore connect --port -``` + +The connection credentials are displayed when the tunnel starts. Make sure to note the password if you need it for your client. + diff --git a/standard/cli/command-reference/porter-env.mdx b/standard/cli/command-reference/porter-env.mdx index 9acea99..ac58754 100644 --- a/standard/cli/command-reference/porter-env.mdx +++ b/standard/cli/command-reference/porter-env.mdx @@ -2,71 +2,174 @@ title: 'porter env' --- -##### Prerequisites +`porter env` contains commands for managing environment variables and secrets. -- You've logged in to the Porter CLI after running [porter auth login](/enterprise/cli/command-reference/porter-auth) -- You're connected to the correct project by running [porter config set-project](/enterprise/cli/command-reference/porter-config) -- You're connected to the correct cluster by running [porter config set-cluster](/enterprise/cli/command-reference/porter-config) +## Prerequisites -### `porter env pull`[](#porter-env 'Direct link to heading') +- 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) +- You're connected to the correct cluster by running [porter config set-cluster](/standard/cli/command-reference/porter-config) -The `porter env` command allows users to pull environment variables from an existing environment group or application. +--- +## Global Flags + +These flags are available on all `porter env` subcommands: + +| Flag | Short | Description | +|------|-------|-------------| +| `--app` | `-a` | Target application | +| `--group` | `-g` | Target environment group | +| `--target` | `-x` | Deployment target name | + + +You must specify either `--app` or `--group`, but not both. + + +--- + +## `porter env pull` + +Pull environment variables from an application or environment group to your local machine. + +**Usage:** +```bash +porter env pull [flags] ``` -porter env pull [args...] -``` -To pull variables from an existing app, you can specify the `-a` flag: +**Options:** + +| Flag | Short | Description | +|------|-------|-------------| +| `--file` | `-f` | Output file path (writes to stdout if not specified) | +| `--variables` | `-v` | Output only variables (excludes secrets) | +| `--secrets` | `-s` | Output only secrets (excludes variables) | + +```bash From Application +porter env pull -a my-app ``` -porter env pull -a [APP_NAME] + +```bash From Environment Group +porter env pull -g production-secrets ``` -To pull variables from an existing environment group, you can specify the `-g` flag: +```bash To File +porter env pull -a my-app -f .env.local +``` +```bash Variables Only +porter env pull -a my-app -v ``` -porter env pull -g [ENV_GROUP_NAME] + +```bash Secrets Only +porter env pull -g my-env-group -s -f secrets.env ``` + -### `porter env set`[](#porter-env-set 'Direct link to heading') + +By default, both variables and secrets are output together. Use `-v` or `-s` to filter. You cannot use both flags at the same time. + -The `porter env set` command allows users to set environment variables and secrets for an existing environment group or application. +--- -``` -porter env set [args...] +## `porter env set` + +Set environment variables and secrets for an application or environment group. + +**Usage:** +```bash +porter env set [flags] ``` -To set variables for an existing app, you can specify the `-a` flag: +**Options:** +| Flag | Short | Description | +|------|-------|-------------| +| `--variables` | `-v` | Variables to set as key=value pairs | +| `--secrets` | `-s` | Secrets to set as key=value pairs | +| `--skip-redeploys` | | Skip re-deploying apps linked to the environment group | + + +```bash Set App Variables +porter env set -a my-app -v KEY1=value1,KEY2=value2 ``` -porter env set -a [APP_NAME] --variables KEY1=VALUE1,KEY2=VALUE2 + +```bash Set Group Variables +porter env set -g my-env-group -v KEY1=value1 ``` -To set variables for an existing environment group, you can specify the `-g` flag: +```bash Set Secrets +porter env set -g my-env-group -s API_KEY=secret123,DB_PASSWORD=pass456 +``` +```bash Set Both +porter env set -g my-env-group \ + -v NODE_ENV=production,LOG_LEVEL=info \ + -s DATABASE_URL=postgres://... ``` -porter env set \ --g [ENV_GROUP_NAME] \ ---variables KEY1=VALUE1,KEY2=VALUE2 \ ---secrets SECRET1=VALUE1,SECRET2=VALUE2 + +```bash Skip Redeploys +porter env set -g my-env-group -v KEY=value --skip-redeploys ``` + -### `porter env unset`[](#porter-env-unset 'Direct link to heading') + +Use `-s/--secrets` for sensitive values like API keys and passwords. These are encrypted and not visible in logs. + -The `porter env unset` command allows users to unset environment variables and secrets for an existing environment group or application. + +When updating an environment group, all apps linked to the group will be re-deployed unless you use `--skip-redeploys`. + -``` -porter env unset [args...] +--- + +## `porter env unset` + +Remove environment variables or secrets from an application or environment group. + +**Usage:** +```bash +porter env unset [flags] ``` -To unset variables for an existing app, you can specify the `-a` flag: +**Options:** +| Flag | Short | Description | +|------|-------|-------------| +| `--variables` | `-v` | Comma-separated list of variable names to remove | +| `--secrets` | `-s` | Comma-separated list of secret names to remove | +| `--skip-redeploys` | | Skip re-deploying apps linked to the environment group | + + +```bash Unset Variables from App +porter env unset -a my-app -v KEY1,KEY2 ``` -porter env unset -a [APP_NAME] --variables KEY1,KEY2 + +```bash Unset Secrets from App +porter env unset -a my-app -s API_KEY,DB_PASSWORD ``` -To unset variables for an existing environment group, you can specify the `-g` flag: +```bash Unset from Group +porter env unset -g my-env-group -v OLD_KEY,UNUSED_VAR +``` +```bash Unset Both Variables and Secrets +porter env unset -g my-env-group -v VAR1 -s SECRET1 ``` -porter env unset -g [ENV_GROUP_NAME] --variables KEY1,KEY2 + +```bash Skip Redeploys +porter env unset -g my-env-group -v KEY --skip-redeploys ``` + + + +When updating an environment group, all apps linked to the group will be re-deployed unless you use `--skip-redeploys`. + + +--- + +## Related Commands + +- [porter app update](/standard/cli/command-reference/porter-app#porter-update) - Update app configuration +- [porter apply](/standard/cli/command-reference/porter-apply) - Deploy with environment variables in porter.yaml diff --git a/standard/cli/command-reference/porter-job.mdx b/standard/cli/command-reference/porter-job.mdx deleted file mode 100644 index 43d5e3f..0000000 --- a/standard/cli/command-reference/porter-job.mdx +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: 'porter job' ---- - -##### Prerequisites - -- You've logged in to the Porter CLI after running [porter auth login](/enterprise/cli/command-reference/porter-auth) -- You're connected to the correct project by running [porter config set-project](/enterprise/cli/command-reference/porter-config) - -### `porter job runs`[](#porter-job-runs 'Direct link to heading') - -The `porter job runs` command allows users to view the job runs for a project, with optional filters applied. The returned job runs will be sorted by creation time, with the most recent job runs appearing first. - -``` -porter job runs [JOB_NAME] -``` - -The following flags can be used to filter the job runs: - -```yaml -# --job: -# filter job runs by job name -porter job runs --job [JOB_NAME] - -# --app: -# filter job runs by application name -porter job runs --app [APP_NAME] - -# --revision: -# filter job runs by revision number (requires --app) -porter job runs --app [APP_NAME] --revision [REVISION_NUMBER] - -# --target: -# filter job runs by deployment target, will use the default target if not provided -# can pass "ALL" to pull runs across all deployment targets -porter job runs --target [TARGET_NAME] - -# --status: -# filter job runs by status -porter job runs --status [STATUS] - -# --limit: -# limit the number of job runs returned, defaults to 100 -porter job runs --limit [LIMIT] -``` diff --git a/standard/cli/command-reference/porter-project.mdx b/standard/cli/command-reference/porter-project.mdx index a5c37f5..d993fc9 100644 --- a/standard/cli/command-reference/porter-project.mdx +++ b/standard/cli/command-reference/porter-project.mdx @@ -1,14 +1,31 @@ --- -title: "porter project" +title: 'porter project' --- -##### Prerequisites +`porter project` contains commands for viewing and managing Porter projects. -* You've logged in to the Porter CLI after running [porter auth login](/enterprise/cli/command-reference/porter-auth) +## Prerequisites - -`porter project` contains commands for interacting with a Porter project. +- You've logged in to the Porter CLI after running [porter auth login](/standard/cli/command-reference/porter-auth) -### `porter project list`[](#porter-project-list "Direct link to heading") +--- + +## `porter project list` + +List all projects that you have access to. + +**Usage:** +```bash +porter project list +``` + + +Use `porter config set-project` to switch between projects after listing them. + + +--- + +## Related Commands -This lists all projects that the authenticated user has access to. \ No newline at end of file +- [porter config set-project](/standard/cli/command-reference/porter-config) - Set the active project +- [porter cluster list](/standard/cli/command-reference/porter-cluster) - List clusters in the current project diff --git a/standard/cli/command-reference/porter-target.mdx b/standard/cli/command-reference/porter-target.mdx index 0f2a021..67e8b80 100644 --- a/standard/cli/command-reference/porter-target.mdx +++ b/standard/cli/command-reference/porter-target.mdx @@ -2,24 +2,62 @@ title: 'porter target' --- -##### Prerequisites +`porter target` contains commands for managing deployment targets. -- You've logged in to the Porter CLI after running [porter auth login](/enterprise/cli/command-reference/porter-auth) -- You're connected to the correct project by running [porter config set-project](/enterprise/cli/command-reference/porter-config) -- You're connected to the correct cluster by running [porter config set-cluster](/enterprise/cli/command-reference/porter-config) +## Prerequisites -### `porter target list`[](#target-list 'Direct link to heading') +- 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) +- You're connected to the correct cluster by running [porter config set-cluster](/standard/cli/command-reference/porter-config) -`porter target list` lists all of the deployment targets in your cluster: +--- -``` -porter target list +## `porter target list` + +List all deployment targets in the current cluster. + +**Usage:** +```bash +porter target list [flags] ``` -To see preview environments, include the `--preview` flag: +**Options:** +| Flag | Description | +|------|-------------| +| `--preview` | Include preview environment targets | + + +```bash List Targets +porter target list ``` + +```bash Include Previews porter target list --preview ``` + + + +Deployment targets allow you to deploy the same application to different environments (production, staging, preview) within the same cluster. + + +--- + +## Using Targets with Deployments + +Specify a target when deploying with `porter apply`: + +```bash +porter apply -f porter.yaml --target staging +``` + + +Preview environment targets are automatically created when you set up preview environments. See [Preview Environments](/preview-environments/overview) for more details. + + +--- +## Related Commands +- [porter apply](/standard/cli/command-reference/porter-apply) - Deploy to a specific target +- [porter app list](/standard/cli/command-reference/porter-app) - List apps in the current target