Prerequisites

​
porter app run

The porter app run command allows users to execute a command on a remote container:

porter app run [APP_NAME] -- [COMMAND] [args...]

The APP_NAME is the name of the application on the Porter dashboard.

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.

To connect to an existing running container, you can specify the -e flag:

porter app run -e [APP_NAME] -- [COMMAND] [args...]

Common Usage 

porter app run [APP_NAME] -- bash

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

You can also use this command to trigger manual job runs for existing jobs in your application using the --job flag.

porter app run [APP_NAME] --job [JOB_NAME]

You can wait for the job to complete before exiting using the --wait flag:

porter app run [APP_NAME] --job [JOB_NAME] --wait

For jobs that do not allow concurrent runs, you can override this behavior using the --allow-concurrent flag:

porter app run [APP_NAME] --job [JOB_NAME] --allow-concurrent

​
porter app logs

The porter app logs command allows users to stream new logs or view historical logs from their application:

porter app logs [APP_NAME]

The following flags can be used to filter the logs:

# --service:
# filter logs by service name
porter app logs [APP_NAME] --service [SERVICE_NAME]

# --search:
# search for a specific string in the logs
porter app logs [APP_NAME] --search [SEARCH_STRING]

# --revision:
# stream logs from a specific revision
porter app logs [APP_NAME] --revision=[REVISION_NUMBER]

By default, the command will stream new logs. Setting the --since flag or the --from --to flags will switch to pulling historical logs:

# --since:
# pull logs over the specified duration
# looking back from the current time
porter app logs [APP_NAME] --since 12h

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

# with timezone:
porter app logs [APP_NAME] --from 2021-01-01T06:00:00-04:00 --to 2021-01-01T08:00:00-04:00

When viewing historical logs, these additional flags can be used:

# --limit:
# the number of lines of historical logs to return
# defaults to 100
porter app logs [APP_NAME] --since 12h --limit=[LIMIT]

# --newest-first:
# return the newest historical logs first
# defaults to true
porter app logs [APP_NAME] --since 12h --newest-first=false

​
porter app build

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.

For example, to start a Docker build for an app in the ./frontend directory, you can run:

porter app build [APP_NAME] --build-context ./frontend --dockerfile ./frontend/Dockerfile

​
porter app push

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 push [APP_NAME] --tag [TAG]

​
porter app update

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.

porter app update [APP_NAME] -f porter.yaml

​
porter app update-tag

porter app update-tag updates the image of the specified application with the tag provided by the --tag flag. For example:

porter app update-tag <YOUR_APP_NAME> --tag <GITHUB_SHA>

This command is functionally equivalent to running either porter apply or porter app update with the --tag flag.