fallow: codebase intelligence for TypeScript and JavaScript

Manage the local license used for paid runtime-coverage features.

fallow license status

Verification is offline against an Ed25519 public key compiled into the binary. Only the trial and refresh flows make 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

JWT input precedence is:

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

Whitespace is normalized before verification, so copied multiline tokens still work.

Flags

Flag	Description
`--trial`	Start a 30-day email-gated trial instead of reading a JWT locally. Requires `--email`. Rate-limited to 5 requests per hour per IP; in CI or behind a shared NAT, start the trial from a developer machine and set `FALLOW_LICENSE` on the runner.
`--email <ADDR>`	Email address for the trial flow. On success, fallow also prints the server-reported `trialEndsAt` ISO timestamp 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 reports that explicitly and tells you to refresh it. If no token is present, the command suggests starting a trial. If the JWT includes a refresh_after claim (issued at iat + 15 days by api.fallow.cloud) and that timestamp has already passed, status appends a one-line refresh hint. This is a proactive nudge while the license is still valid, not an error.

`refresh`

Fetch a fresh JWT for the currently active license.

fallow license refresh

This is the preferred way to renew a token before the hard-fail window is reached.

`deactivate`

Remove the local license file.

fallow license deactivate

Storage and precedence

By default, the local token is stored at ~/.fallow/license.jwt. On Unix, fallow writes the file with mode 0600 (owner read/write only) so other users on the same host cannot read the bearer token. Windows relies on the ACL of the containing directory. Lookup precedence is:

FALLOW_LICENSE
FALLOW_LICENSE_PATH
~/.fallow/license.jwt

Use FALLOW_LICENSE on shared CI runners where writing to a user home directory is not desirable.

Exit behavior

Common outcomes:

Situation	Result
Valid license	exit code `0`
No license or hard-fail expired license	non-zero status
Network failure during `--trial` or `refresh`	exit code `7`
Malformed or truncated JWT	non-zero status with a verification error

Actionable error messages

When the backend returns a structured error envelope, fallow maps known code values to targeted hints instead of printing the raw HTTP body:

Operation + code	Message
`refresh` + `token_stale`	`your stored license is too stale to refresh. Reactivate with: fallow license activate --trial --email <addr>` (fires when the stored JWT is more than 45 days past its `exp`)
`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 unknown codes, fallow surfaces the backend’s message field if present, otherwise the raw body.

Clock skew

License verification rejects JWTs whose iat (issued-at) claim is more than 24 hours in the future relative to the local system clock. The same check catches both directions of skew: a JWT signed against a forward-shifted clock and a local machine whose clock is behind reality. Rejection surfaces as a license appears to be issued <duration> in the future error and exits non-zero so paid features fail closed instead of silently honoring a license the local clock cannot validate against. Common non-user causes:

CI containers booted without NTP.
Machines with a dead BIOS battery.
A laptop’s clock drifting after a long sleep.

After confirming the system clock is correct, the default 24h window can be overridden via FALLOW_LICENSE_SKEW_TOLERANCE_SECONDS=<seconds> for environments with predictable drift. Parsing is lenient: unset, empty, unparsable, or negative values all fall back to the default so a typo in a runner env block cannot fail license verification on its own.

Runtime coverage

Understand what the paid runtime-coverage layer adds on top of health analysis.

Coverage setup

Guided first-run workflow that bootstraps the sidecar and writes a collection recipe.

Commands

fallow license

Subcommands

`activate`

Flags

`status`

`refresh`

`deactivate`

Storage and precedence

Exit behavior

Actionable error messages

Clock skew

See also

Runtime coverage

Coverage setup

​Subcommands

​activate

​Flags

​status

​refresh

​deactivate

​Storage and precedence

​Exit behavior

​Actionable error messages

​Clock skew

​See also

Runtime coverage

Coverage setup

Subcommands

`activate`

Flags

`status`

`refresh`

`deactivate`

Storage and precedence

Exit behavior

Actionable error messages

Clock skew

See also