swell Command Reference

This page lists every swell command and the flags it accepts. It is a lookup page. If you are setting swell up for the first time, read swell and swell Configuration first, and come back here for the flag you cannot remember.

Two conventions hold throughout. Commands are noun then verb, so it is swell objects upload, not swell upload objects. Flag names are snake_case, so it is --environment_id, never --environmentId or --environment-id. And every command, at every level, takes --help.

Every command

"Needs an environment" means the command fails without --environment_id, or the equivalent environment variable or config file entry. swell verify needs neither an environment nor credentials, which is what makes it usable on a host that has never talked to Stairwell.

Global flags

Available on every command. Each one can also be set by environment variable or config file; swell Configuration covers the naming and the precedence.

auth

Manages the stored credentials in ~/.config/swell/credentials.yaml.

login prints a URL, waits for you to paste back the token Stairwell shows you in the browser, then looks up and stores your user and organization alongside it. logout clears all three.

completion

Prints a bash completion script to standard output. Source it into the current shell, or add the same line to your shell startup file to get completion in every session.

config

Prints the configuration in force after flags, environment variables, the config file, and defaults have been resolved. It includes your auth token in the clear.

foundation

Creates and lists the things an environment is made of.

What each returns:

getenvs is the command to reach for first on a new machine: it is the shortest path to the environment ID every other command wants.

getmatches walks every rule in the environment and pages through all matches for each one, so it is slow and returns a lot on an environment with many rules. For a rule you already have in mind, swell query files with a rule condition is faster, and Manage YARA Rules covers the same ground in the app.

objects

objects upload

Notes:

• --asset takes an asset ID, not an asset name. If you leave it off, upload uses the asset_id that swell onboard wrote to your config file, so onboarding once is enough to start uploading. Get an ID from swell onboard, swell foundation mkasset, or the default asset ID in swell foundation getenvs.
• Directories are walked recursively. Passing a directory sends everything under it that passes the size limit, which is how a one-off sweep of an appliance is done.
• --parallel controls how many files are in flight, defaulting to one worker per available CPU. Lower it on a production host you do not want to load.
• Set --format to match what you are sending. With zip, gzip, or 7z, Stairwell unpacks the archive and the files inside it appear in your environment as their own objects. With raw, the archive itself is the object.
• --store_filename=false sends the file content without its name or path. Use it when the path itself is sensitive. You give up searching on filename for those uploads.
• The command exits non-zero and names every path it could not upload, so a scheduled job can be gated on it.

objects download

Each file is written under a filename equal to its SHA256. The command refuses rather than overwrite a file that is already there, and it does not create the target directory for you. Downloaded files are the real thing: write them somewhere your own endpoint protection will not act on them.

objects filter

Intake filters drop files as they arrive, at the point of ingest, before anything is stored. Filters are per environment and each one has a name that has to be unique within the environment.

Read the direction carefully, because it is the opposite of a search filter: a filter that evaluates to true drops the file. An environment can hold several filters, and a file is dropped if any one of them matches.

The expression is written in CEL and has to resolve to a boolean. Two variables are available:

Quote the expression, because it will contain characters your shell wants to interpret.

list prints one row per filter with its name and its expression, which is the fastest way to see what an environment is currently dropping. There is no update verb, so to change a filter, create the replacement and then delete the old one, in that order, so there is no window where neither is in place.

onboard

Creates an asset in the environment you named and prints its ID, then writes the configuration in force back out to ~/.config/swell/swell.yaml, including the new asset ID.

Two consequences. Run onboard before you hand-edit that config file, not after. And swell objects upload picks that asset up automatically, so you do not need to pass --asset again unless you want a different one.

The name is for you: it is what the machine is called in the Assets view. The ID is what commands take.

query

Runs the same queries as the search box in the app and prints results as a table, or as JSON for a script to read.

Notes:

• The query argument is CEL, the same language the app's filter boxes take. Quote it. Omitting it returns everything in the environment, subject to one page of results.
• One environment at a time. query scopes to the single environment in --environment_id.
• assets, files, and rules take a --timeout, defaulting to two minutes. A broad query against a large environment can still exceed it, and the error says so and names the flag. Raise it for a deliberately wide sweep, or run the query in the app, where Hunting and Search covers the wider surface.
• --json emits a single array, which is the form to read from a script.

tags

A tag is a key and a value attached to one asset, one file, or one YARA rule. Tags are per environment.

Entity flags. Exactly one entity has to be identified, and identifying two is an error:

--rule.version and --rule.environment_id only mean anything alongside --rule.name, and --rule.name is the one case where swell tags list needs an environment: it uses --environment_id when --rule.environment_id is not given.

tags list reports every tag on the entity across all the environments you can reach, and prints the environment each tag came from. That is deliberate: the same file can carry different tags in different environments, and knowing which environment a tag came from is usually the point of asking.

verify

Diagnostics you run before deploying. Neither subcommand needs credentials or an environment. Pre-Deployment Check covers how to read the output and what to do when a probe fails.

connectivity probes four endpoints from the machine you run it on: the web app, the API, HTTP intake, and gRPC intake. Each probe gets ten seconds. An HTTP error response still counts as reachable, because the probe tests the path and not your credentials; what fails a probe is a network or TLS error. A failure on either gRPC row is reported as a warning and does not change the exit code. Any other failure makes the command exit non-zero, so it works as a gate in whatever tooling pushes your installs.

compatibility reports what is on the host that commonly needs an exclusion: endpoint protection and proxy clients it recognizes, the state of the host firewall, and any proxy environment variables that are set. It makes no network calls and sends nothing to Stairwell.

yara

yara list

Prints every rule at its current version, with the rule name, that version, and whether the rule is active, sorted by name. It pages through the whole environment rather than returning one page.

yara upload

Notes:

• A file can hold many rules and each one is uploaded separately. The output names the file and the rule for every success and every failure, so a partial result is legible.
• Without --recursive, subdirectories are skipped and named on standard error rather than silently ignored. The directory you pass on the command line is always read.
• --replace_existing_rules is what you want in a pipeline. Without it, a rule whose name already exists in the environment is a failure, so re-running the same push fails the second time.
• Private and global rules are skipped, with a line on standard error naming each one. Split them out if you were relying on them.
• Rule uploads are capped at sixteen at a time, whatever --parallel says, to stay inside the server's rate limits.

Rules pushed this way behave exactly like rules written in the app, so Writing Your First YARA Rule and YARA Rule Best Practices apply unchanged.

yara download

Writes every rule in the environment to its own file, named for the rule with a .yara extension. Without --force, the command stops at the first file that already exists, so a re-run into the same directory does nothing until you either clear it or pass the flag.

Watch the short form here. On yara download, -f is --force. On yara upload and objects upload, -f is --file. Spell both out in a script.

yara delete

Deletion is per version, and only the current version can be deleted. Read the version out of swell yara list immediately before you delete rather than from a value you cached earlier.

version

Prints the version of swell you are running. Quote it in any support request, because it is the first thing that explains behavior not matching this page.

What should I read next?

• swell Configuration, for precedence, the config file, and multiple deployments.
• Pre-Deployment Check, for the checks that go before a forwarder rollout.
• CEL Query Language, for the syntax swell query and intake filters take.