swell Configuration

Every swell setting can come from four places, and they are ranked. An explicit flag beats an environment variable, which beats the config file, which beats the built-in default. So --environment_id=X on the command line wins over SWELL_ENVIRONMENT_ID in your shell, which wins over environment_id in ~/.config/swell/swell.yaml. Nothing merges and nothing warns: the highest-ranked source that has a value for a setting supplies it, and the rest are ignored for that setting.

Which setting wins when two disagree?

Highest to lowest:

Two settings have a fifth source below all of these: auth_token and organization_id also live in the credentials file that swell auth login writes. That file is consulted only when ranks 1 through 3 have said nothing. It is deliberately the weakest source, so that logging in never quietly overrides a token you configured on purpose.

That ranking is where most confusion comes from. If a command is reaching the wrong environment, or authenticating as somebody else, print what swell actually resolved:

$ swell config

swell config writes out the effective configuration, every setting with the value in force after the ranking above is applied. It prints your auth token in the clear, so treat the output like a credential and do not paste it into a ticket.

Where does swell keep its configuration?

Two files, both in ~/.config/swell/:

On Windows the same paths apply under your user profile, and swell marks the .config directory hidden.

Keep them separate for the reason the split implies: swell.yaml is a file you can commit to a repository of operational config, and credentials.yaml is a secret written with owner-only permissions. Do not move the token into swell.yaml unless you mean to give it the higher precedence that comes with it.

One thing to know about swell onboard: as well as creating the asset, it writes the effective configuration back out to ~/.config/swell/swell.yaml, including the ID of the asset it created. Run it before you hand-edit that file rather than after. swell objects upload then uses that asset without being told, so onboarding once is enough to start uploading. Pass --asset when you want a different one; the flag wins.

How do I authenticate?

$ swell auth login

swell prints a URL, you open it in a browser and sign in if you are not already, Stairwell shows you a token, and you paste it back at the prompt. swell then looks up the user and organization that token belongs to and writes all three to credentials.yaml. Later commands need no token on the command line.

$ swell auth logout

That clears the stored token, user, and organization.

Three details worth knowing:

• A token you configure yourself takes precedence over the stored one. If you have auth_token in your config file or SWELL_AUTH_TOKEN in your shell, that is the token in use, and the stored one is ignored.
• If that happens, swell tells you. You get a warning naming the configured source, because the failure it prevents is spending an afternoon wondering why auth login as one user did not change anything. Remove the config file entry, unset the variable, or run swell auth logout, whichever matches what you meant.
• If your account can reach more than one organization, the first one Stairwell returns is stored. Override it with --organization_id, or edit the value in credentials.yaml.

For automation, do not run auth login at all. Put the token in SWELL_AUTH_TOKEN from your secret store and leave no credentials file on the machine.

What can I set, and what is it called?

These settings are available to every command. Flag names are snake_case throughout swell, and the config file key is the flag name without the leading dashes.

The three address settings exist so that a Stairwell engineer can point swell at a local server, and so that you can point it somewhere else if you are ever asked to. Leave them alone otherwise.

--insecure and --plaintext turn off the protections that make the connection trustworthy. They are for a server running on your own laptop. If you are reaching for either one to get past a certificate error against Stairwell's real endpoints, the certificate error is the finding: something is intercepting the connection, and Pre-Deployment Check explains what to do about it.

How do I set one of these with an environment variable?

Take the flag name, uppercase it, and put SWELL_ in front. So auth_token becomes SWELL_AUTH_TOKEN, and environment_id becomes SWELL_ENVIRONMENT_ID. The pattern holds for every setting in the table above.

export SWELL_AUTH_TOKEN=...
export SWELL_ENVIRONMENT_ID=...
swell yara list

This is the form to use in CI, in a container, and in a scheduled job: no file to place on the host, no token in a command line that shows up in the process list.

What does a config file look like?

YAML, with one key per setting:

environment_id: 'YOUR_ENVIRONMENT_ID'
parallel: 8

That is enough to turn swell yara list --environment_id=YOUR_ENVIRONMENT_ID into swell yara list. Other formats that the underlying configuration library understands also work, but YAML is the one we test and the one every example here uses.

How do I keep separate configs for separate deployments?

Give each one its own file and select it per command. This is the normal shape for anyone working across a production environment and a staging one, or for a service provider working across several customers.

# ~/swell_prod.yaml
environment_id: 'PROD_ENVIRONMENT_ID'

# ~/swell_staging.yaml
environment_id: 'STAGING_ENVIRONMENT_ID'

Then pick one:

$ swell --config_file=~/swell_staging.yaml yara list
$ swell --config_file=~/swell_prod.yaml yara list

Or set it in the environment instead, which is the version to prefer when you are about to run several commands against one deployment and do not want the fifth one to land in the wrong place:

$ export SWELL_CONFIG_FILE=~/swell_prod.yaml

Either works. If you name a file explicitly and it is missing or unreadable, swell stops with an error rather than quietly falling back to the default file, because silently running against the wrong deployment is the worse outcome.

Two habits make this safer. Name the files after the environment rather than after dev and prod, because those two words mean different things to different teams. And put the environment name in your shell prompt if you switch often; a command that ran against the wrong environment is at best a confusing result and at worst a rule pushed somewhere you did not intend.

What should I read next?

• swell Command Reference, for every command and its flags.
• Environments, for what an environment is and why nearly every command needs one.
• Pre-Deployment Check, for the connectivity and compatibility checks.