Skip to main content
Live. This area is documented as current, user-reliable behavior.

​
Goal

Operate a project without accidental shell evaluation or destructive environment replacement.

​
Prerequisites

  • An authenticated profile
  • An existing project with the required operation access

​
Workflow

1
Read or follow the specific log source you need.
2
Use structured argv for remote commands unless shell syntax is intentional.
3
Set or delete one environment variable at a time for routine changes.
4
Use dotenv import only for deliberate bulk updates.

​
Read recent logs

The default source is application. Non-following application, HTTP, and build logs support --lines; the default is 100.

​
Follow streams

Add --follow or -f for SSE streaming. The client ignores heartbeat events, reconnects after retryable failures, and sends the last event ID when reconnecting.
  • Deployment logs require --follow.
  • Build logs require --build BUILD_ID.
  • Streaming text is written directly to standard output.

​
Structured remote execution

Arguments after the project are sent as an argv array by default. Operators such as &&, pipes, redirects, and variable expansion have no shell meaning in this mode.

​
Explicit shell execution

Use --shell only when shell evaluation is required. The CLI then joins the supplied arguments into one command string and marks the request as a shell operation.
  • The remote timeout defaults to 600 seconds.
  • Remote standard output and standard error preserve their respective local streams.
  • Remote exit codes from 1 through 125 are returned as the CLI process exit code.

​
List environment variables

Secret values are redacted by default. Revealing them requires both --show-secrets and --yes; treat the resulting terminal and redirected output as sensitive.

​
Set one variable

Setting one key uses an individual PUT contract and does not replace unrelated variables. Values are treated as secrets by default and receive a 90-day rotation reminder.

​
Delete or import

Deleting one key is confirmation-gated. Dotenv import accepts a file or standard input and is limited to 1 MiB.

​
Environment selection

The global --environment value overrides the profile default. The selected environment is applied to list, set, delete, and import requests.

​
Expected result

Operational output reaches the correct stream and environment changes affect only the requested keys.

​
Common failures

  • Deployment logs are requested without --follow.
  • Build logs are requested without --build.
  • A remote command omits the -- separator before argv.
  • --value and --value-stdin are supplied together.
  • A non-interactive delete omits --yes.
  • Dotenv input exceeds 1 MiB.

Deploy Git revisions and local directories

Deploy a branch, tag, commit, or deterministic local source archive and follow the rollout.

Profiles, defaults, and global options

Use profiles for API and resource defaults, then override them explicitly for one command.

Output, pagination, errors, and automation

Select stable machine output, fetch paginated results, and handle documented exit codes.