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

# Profiles, defaults, and global options

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

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

## Goal

Configure repeatable project and application contexts without storing credentials in YAML.

## Prerequisites

* The StackShift CLI is installed

## Workflow

<Steps>
  <Step>
    Inspect the built-in default profile.
  </Step>

  <Step>
    Create additional profiles only when you need a different API or default resource set.
  </Step>

  <Step>
    Select an active profile or override it for one command.
  </Step>

  <Step>
    Use global flags for temporary resource, output, timeout, and confirmation choices.
  </Step>
</Steps>

## Default profile

When no configuration file exists, the CLI uses a `default` profile pointing to `https://api.stackshift.cloud`. The first command that saves configuration creates an owner-only directory and a mode-`0600` file on Unix.

Profile YAML stores no token. The matching credential is stored separately in the operating-system credential manager.

```bash theme={null}
stackshift context list
```

## Create or update a profile

A new profile requires `--api-url`. Updating an existing profile preserves its API URL when that flag is omitted, while the resource defaults are replaced by the values supplied to the command.

```bash theme={null}
stackshift context set production \
  --api-url https://api.stackshift.cloud \
  --project checkout-api \
  --app commerce \
  --environment production

stackshift context use production
stackshift context list
```

## Override precedence

* `--profile` selects a profile for one process; otherwise the current profile is used.
* `--api-url` overrides `STACKSHIFT_API_URL`, which overrides the profile API URL.
* An API URL must use HTTPS, except `http://localhost` and `http://127.0.0.1`.
* A positional project overrides `--project`, which overrides the profile default project.
* `--app` overrides the profile default application.
* `--environment` overrides the profile default environment.

## Global options

* `--profile`: configuration profile for this process.
* `--api-url`: StackShift API URL override.
* `--project`, `--app`, `--environment`: resource selection overrides.
* `--output` or `-o`: `table`, `json`, `yaml`, or `name`.
* `--timeout`: request timeout; the default is 30 seconds.
* `--yes` or `-y`: approve confirmation-gated operations.
* `--quiet` or `-q`: suppress progress output.
* `--color`: `auto`, `always`, or `never`.
* `--debug`: write redacted request diagnostics to standard error.
* `--token-file`, `--token-stdin`: explicit CI credential sources.

## Resource resolution

UUIDs are used directly. Supported named resources are resolved with exact, case-insensitive matching against names, slugs, keys, or domain fields as appropriate.

If no match exists, the command fails. If more than one resource matches, the command fails and asks for an ID instead of choosing one.

## Expected result

<Check>
  Commands resolve the intended API, project, application, and environment predictably.
</Check>

## Common failures

<Warning>
  * A new profile is created without `--api-url`.
  * A profile name does not exist.
  * A saved resource name was renamed or became ambiguous.
  * A non-local API URL uses plain HTTP.
</Warning>

## Related guides

<CardGroup cols={2}>
  <Card title="Authentication and credential storage" href="/cli/authentication">
    Use browser authorization interactively and explicit, non-persistent token inputs in CI.
  </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>