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

​
Goal

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

​
Prerequisites

  • The StackShift CLI is installed

​
Workflow

1
Inspect the built-in default profile.
2
Create additional profiles only when you need a different API or default resource set.
3
Select an active profile or override it for one command.
4
Use global flags for temporary resource, output, timeout, and confirmation choices.

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

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

​
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

Commands resolve the intended API, project, application, and environment predictably.

​
Common failures

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

Authentication and credential storage

Use browser authorization interactively and explicit, non-persistent token inputs in CI.

Output, pagination, errors, and automation

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