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

# Logs, remote execution, and environment variables

> Inspect runtime output, execute structured commands, and mutate environment variables safely.

<Tip>
  **Live.** This area is documented as current, user-reliable behavior.
</Tip>

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

<Steps>
  <Step>
    Read or follow the specific log source you need.
  </Step>

  <Step>
    Use structured argv for remote commands unless shell syntax is intentional.
  </Step>

  <Step>
    Set or delete one environment variable at a time for routine changes.
  </Step>

  <Step>
    Use dotenv import only for deliberate bulk updates.
  </Step>
</Steps>

## Read recent logs

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

```bash theme={null}
stackshift logs checkout-api --lines 200
stackshift logs checkout-api --source http --lines 50
stackshift logs checkout-api --source build --build BUILD_ID
```

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

```bash theme={null}
stackshift logs checkout-api --follow
stackshift logs checkout-api --source http --follow
stackshift logs checkout-api --source deployment --follow
stackshift logs checkout-api --source build --build BUILD_ID --follow
```

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

```bash theme={null}
stackshift exec checkout-api -- php artisan migrate --force
stackshift exec checkout-api --command-timeout 120 -- npm run healthcheck
stackshift exec checkout-api --reason "database migration" -- ./migrate
```

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

```bash theme={null}
stackshift exec checkout-api --shell -- \
  'php artisan migrate && php artisan cache:clear'
```

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

```bash theme={null}
stackshift env list checkout-api
stackshift env list checkout-api --environment staging -o json
stackshift env list checkout-api --show-secrets --yes
```

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

```bash theme={null}
stackshift env set checkout-api DATABASE_URL --value "$DATABASE_URL"
printf '%s\n' "$API_KEY" | \
  stackshift env set checkout-api API_KEY --value-stdin
stackshift env set checkout-api LOG_LEVEL --value info --secret=false
stackshift env set checkout-api API_KEY --value "$API_KEY" --rotation-days 30
```

## Delete or import

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

```bash theme={null}
stackshift env delete checkout-api OLD_KEY
stackshift env delete checkout-api OLD_KEY --yes
stackshift env import checkout-api --file .env.production
generate-env | stackshift env import checkout-api --file -
```

## Environment selection

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

## Expected result

<Check>
  Operational output reaches the correct stream and environment changes affect only the requested keys.
</Check>

## Common failures

<Warning>
  * 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.
</Warning>

## Related guides

<CardGroup cols={2}>
  <Card title="Deploy Git revisions and local directories" href="/cli/deployments">
    Deploy a branch, tag, commit, or deterministic local source archive and follow the rollout.
  </Card>

  <Card title="Profiles, defaults, and global options" href="/cli/profiles-and-global-options">
    Use profiles for API and resource defaults, then override them explicitly for one command.
  </Card>

  <Card title="Output, pagination, errors, and automation" href="/cli/output-and-automation">
    Select stable machine output, fetch paginated results, and handle documented exit codes.
  </Card>
</CardGroup>