fallow license

Turn on continuous and multi-capture runtime coverage on your machine or CI runner. Fallow license activates a trial or JWT, shows status, refreshes a license, or deactivates the local token.

Use fallow license to manage the local license for runtime coverage, which is part of Fallow Cloud, the paid product.

You need a license only for continuous or multi-capture runtime monitoring. A single local capture is free and needs no license. All static analysis is free and open source (MIT). For pricing and tiers, see fallow.tools/pricing.

fallow license status

Fallow verifies the license offline, against an Ed25519 public key in the binary. Only the trial and refresh flows send network requests to api.fallow.cloud.

Subcommands

`activate`

Activate a local JWT or start a 30-day email-gated trial.

fallow license activate --trial --email you@company.com
fallow license activate eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9...
fallow license activate --from-file ./license.jwt
cat ./license.jwt | fallow license activate --stdin

Fallow reads the JWT from the first source that is present:

positional JWT argument
--from-file <path>
--stdin

Fallow normalizes whitespace before verification, so a copied multiline token still works.

Flags

Flag	Description
`--trial`	Start a 30-day email-gated trial, and do not read a local JWT. Requires `--email`. Rate-limited to 5 requests per hour per IP. In CI or behind a shared NAT, start the trial on a developer machine and set `FALLOW_LICENSE` on the runner.
`--email <ADDR>`	Email address for the trial flow. On success, fallow also prints the `trialEndsAt` ISO timestamp from the server, so you do not need to decode the JWT.
`--from-file <PATH>`	Read a JWT from a file.
`--stdin`	Read a JWT from standard input.

`status`

Print the current license status, tier, seats, enabled features, and expiry state.

fallow license status

Example output:

license: VALID, tier=trial seats=1 features=runtime_coverage days_until_expiry=29
  → runtime_coverage: ENABLED

If the token is expired but still in the grace window, fallow says so and tells you to refresh it. If no token is present, the command suggests a trial.

api.fallow.cloud can set a refresh_after claim in the JWT, at iat + 15 days. When that time has passed, status adds a one-line refresh hint. The hint is not an error. It comes while the license is still valid, so you can refresh early.

`refresh`

Fetch a fresh JWT for the currently active license.

fallow license refresh

Use refresh to renew a token before it reaches the hard-fail window.

Fallow first sends the stored license JWT. When no JWT is stored, or the server reports it as too stale to refresh, fallow tries again with a full-access API key. Generate the key at fallow.cloud/settings.

Flag	Description
`--api-key <KEY>`	Fallow Cloud API key for the retry. Overrides `FALLOW_API_KEY`. On a shared CI runner, set `FALLOW_API_KEY` instead: other processes can see a key on the command line, and it can go into the shell history.

`deactivate`

Remove the local license file.

fallow license deactivate

Storage and precedence

By default, fallow stores the local token at ~/.fallow/license.jwt. On Unix, fallow writes the file with mode 0600 (only the owner can read and write). Other users on the same host thus cannot read the bearer token. On Windows, the ACL of the parent directory controls access.

Fallow looks for the license in this order:

FALLOW_LICENSE
FALLOW_LICENSE_PATH
~/.fallow/license.jwt

On a shared CI runner where you do not want to write to a home directory, use FALLOW_LICENSE.

Exit behavior

Situation	Exit code
`status` with a valid license, or a license in the grace period	`0`
`status` with no license, or a license more than 30 days past expiry	`3`
`activate` with a malformed, truncated, or not valid JWT	`3`
`activate --trial` without `--email`	`2`
`activate --trial` or `refresh` fails: network error, rate limit, or rejection by the server	`7`

Grace period

When a license expires, fallow gives you a grace period before it blocks runtime coverage:

Days after expiry	Behavior
1 to 7	Runtime coverage runs as normal. `status` tells you to refresh.
8 to 30	Runtime coverage runs. Its output gets the `license-expired-grace` watermark and verdict.
31 or more	Fallow blocks runtime coverage with exit code `3`.

Runtime coverage runs

Commands that take --runtime-coverage (health, audit, security, and coverage analyze) check the license before they start the sidecar:

With no license, the run continues. A single local capture works. The sidecar rejects continuous or multi-capture input.
With a license present, fallow checks it also for a single capture. A token that is not valid, a license more than 30 days past expiry, or a license without the runtime_coverage feature stops the run with exit code 3.

To go back to the free single-capture mode, run fallow license deactivate and unset FALLOW_LICENSE and FALLOW_LICENSE_PATH.

Actionable error messages

When the backend returns a structured error envelope, fallow shows a specific hint for each known code value. It does not print the raw HTTP body:

Operation + code	Message
`refresh` + `token_stale`	your stored license is too stale to refresh: set FALLOW_API_KEY to a full-access key and run `fallow license refresh` again (generate one at https://fallow.cloud/settings#api-keys)
`refresh` + `invalid_token`	`your stored license token is missing required claims. Reactivate with: fallow license activate --trial --email <addr>`
`refresh` or `trial` + `unauthorized`	`authentication failed. Reactivate with: fallow license activate --trial --email <addr>`
`trial` + `rate_limit_exceeded`	`trial creation is rate-limited to 5 per hour per IP. Wait an hour or retry from a different network (in CI, start the trial locally and set FALLOW_LICENSE on the runner).`

For an unknown code, fallow prints the message field from the backend. If that field is missing, fallow prints the raw body.

Clock skew

License verification rejects a JWT when its iat (issued-at) claim is more than 24 hours in the future, relative to the local system clock. The same check finds skew in both directions:

a JWT signed with a clock that is ahead
a local machine with a clock that is behind

On rejection, fallow prints a license appears to be issued <duration> in the future error and exits non-zero. Licensed features thus fail closed. Fallow does not accept a license that the local clock cannot validate.

Common causes that are not user errors:

CI containers booted without NTP.
Machines with a dead BIOS battery.
A laptop clock that drifts after a long sleep.

For an environment with predictable drift, first make sure that the system clock is correct. Then set FALLOW_LICENSE_SKEW_TOLERANCE_SECONDS=<seconds> to change the default 24h window. Fallow parses this value leniently. An unset, empty, unparsable, or negative value falls back to the default, so a typo in a runner env block cannot cause a license verification failure by itself.