Skip to content
Esc
↑↓navigate↵open⌘Jpreview
On this page

rules

List, add, remove, test, and validate a Space's firewall and cache-bypass rules, and pause or resume every rule at once

sf rules manages a Space’s traffic rules: what it blocks, challenges, or serves past the cache. For what the rules do and where they live, see Traffic rules.

Every command here takes the global flags (--api-url, --profile, --token, -y/--yes, --json) and the space selection flags (--space, -T/--team, --claim-token). See the CLI overview.

sf rules with no subcommand prints the help for the group.

sf rules list

List the Space’s traffic rules in the order the edge reads them. Aliased as sf rules ls.

sf rules list [--space <value>]

No command-specific flags.

sf rules list --space docs

Output

A table of NAME | KIND | ACTION | ORIGIN | WHERE | STATE.

Column Values
NAME The name the author gave the rule, otherwise its name at the edge
KIND firewall, cache-bypass, redirect, rewrite, or header
ACTION block, block <status>, challenge, bypass, or -
ORIGIN file, config, overlay, or platform
WHERE edge or origin
STATE The edge state (pending, live, invalid, over_quota, failed, unknown), or disabled or suspended for a rule that is not enabled

Lines after the table:

  • Rules are paused. This space serves as if it declared none. before the table, while rules are paused.
  • <name>: <message> for a rule the edge refused.
  • <name>: <reason> for a rule that runs at the origin, with a code such as edge_ineligible_capture.
  • <name> was skipped: an earlier rule already has this name. or ... already does the same thing. for a rule the edge never got.
  • Answers on: <hostnames>.
  • Edge rules: <used>/<limit>. When the edge does not answer, the line says the count is Spacefast’s own record or that the limit is unknown.

With no rules, it prints No traffic rules. Declare one in sf.jsonc, or add one: and sf rules add on stderr.

With --json, data is the listSpaceTrafficRules response: { rules, quota, paused, hostnames, collapsed }.

sf rules add

Add a firewall or cache-bypass rule to the Space settings. The rule goes first in its list, so it answers before the rules already there. The change reaches the edge without a publish.

sf rules add --kind firewall|cache-bypass [--action block|challenge] [--status <400-499>]
  [--name <value>] [--description <value>] [--any] [match flags] [--no-wait] [--space <value>]

Rule flags

Flag Default What it does
--kind=<option> required firewall or cache-bypass
--action=<option> none block or challenge. Required for a firewall rule. Refused for a cache-bypass rule
--status=<n> 403 Status a blocked request gets, 400 to 499. Blocks only
--name=<value> none Lowercase letters, digits, -, and _, up to 61 characters. Not all digits and not a reserved word. sf rules remove addresses the rule by it
--description=<value> none What the rule is for
--any false Fire when any match field holds. By default all of them have to
--[no-]wait true Wait until the edge answers for the rule

Match flags

Give at least one. Every match flag repeats.

Flag Matches Commas
--path=<value> Request path, for example '/wp-login.php*' Taken verbatim
--host=<value> Request hostname Taken verbatim
--method=<value> HTTP method Split
--ip=<value> Client address, or a CIDR range like 203.0.113.0/24 Split
--country=<value> Two-letter country codes, for example US,CA Split
--asn=<value> The client network’s ASN Split
--user-agent=<value> User agent, for example '*bot*' Taken verbatim
--referer=<value> The Referer header Taken verbatim
--header=<name=value> A header condition Taken verbatim
--cookie=<name=value> A cookie condition Taken verbatim
--query=<name=value> A query parameter condition Taken verbatim
--extension=<value> Path extension without the dot, for example php Split
--ja3=<value> TLS JA3 fingerprint Split
--ja4=<value> TLS JA4 fingerprint Split
--not=<field> Match the opposite of one field, for example --not country. A header, cookie, or query field names its key: --not header:x-api-client

A value with a * matches as a wildcard. Several values match any of them. An --ip value with a / matches a range. Header names in --not ignore case. Cookie and query names do not.

sf rules add --kind firewall --action challenge --path '/wp-login.php*'
sf rules add --kind firewall --action block --country US,CA --not country
sf rules add --kind cache-bypass --path '/api/*'
sf rules add --kind firewall --action block --status 429 --user-agent '*bot*' --name no-bots

Output

Added <kind> rule <name> on stderr, then what the edge did. When stdout is not a terminal, the rule name also prints alone on stdout.

Line When
Live at the edge. The edge answers with the rule
The edge left this rule <state>: <message> The edge refused the rule or left it over quota
Still applying; run `sf rules list` to check. The wait ran out, or --no-wait was set and the edge has not answered yet

If the config file declares a rule with the same name and kind, the command also prints <name> is also declared in <file>; this rule replaces it until you remove one.

A wait that runs out does not fail the command. The settings write already landed.

With --json, data is { rule, space }. rule is the rule as listSpaceTrafficRules reports it, or null.

Errors

Code Exit When
validation_error 2 --kind is missing or not firewall or cache-bypass
validation_error 2 A firewall rule without --action, or a cache-bypass rule with --action or --status
validation_error 2 No match flag
validation_error 2 --header, --cookie, or --query is not name=value
validation_error 2 --not names a field that is not a match field, names a header, cookie, or query without its key, or names a field the rule does not match on
validation_error 2 --name breaks the name grammar, or the Space settings already declare a rule of this kind with that name

sf rules remove

Remove a rule the Space settings declare. Aliased as sf rules rm.

sf rules remove <name> [--kind firewall|cache-bypass] [--no-wait] [--space <value>]

Arguments

Argument What it is
<name> Name of the rule to remove. Required

Flags

Flag Default What it does
--kind=<option> none firewall or cache-bypass. Needed when both lists have a rule with this name
--[no-]wait true Wait until the edge no longer holds the rule

The command prompts for confirmation unless you pass -y. A rule that a config file declares is not removable here. Delete it from the file and publish.

sf rules remove block-logins --kind firewall
sf rules remove fresh-api --yes

Output

Removed <kind> rule <name> on stderr, then Gone from the edge. or Still applying; run `sf rules list` to check.

If the config file declares a rule with the same name, the command also prints <name> is still declared in <file>; the edge keeps that rule.

With --json, data is { removed: { name, kind }, space }.

Errors

Code Exit When
validation_error 2 --kind is not firewall or cache-bypass
validation_error 2 The name is on a firewall rule and a cache-bypass rule, and --kind is absent
validation_error 2 --kind names one list, and the rule is in the other
validation_error 2 The config file declares the rule: <name> is declared in <file>; remove it there and publish.
rule_not_found 20 The Space declares no rule with this name
confirmation_required 2 No terminal to prompt on, and no --yes
cancelled 130 You answered no at the prompt

sf rules pause

Park every traffic rule at the edge. The Space then serves as if it declared none. The rules stay saved, and a rule added while paused is parked when it arrives.

sf rules pause [--space <value>]

No command-specific flags.

sf rules pause --space docs

Output

Paused this space's traffic rules. It now serves as if it declared none.

With --json, data is the pauseSpaceTrafficRules response, the same shape as sf rules list.

Errors

Code Exit When
traffic_rules_unavailable 30 The Space has no edge yet. Publish it once

sf rules resume

Put every parked rule back into the state it was paused from. Safe to run on a Space that is not paused.

sf rules resume [--space <value>]

No command-specific flags.

sf rules resume --space docs

Output

Resumed this space's traffic rules., then the same listing as sf rules list.

With --json, data is the resumeSpaceTrafficRules response, the same shape as sf rules list.

Errors

Code Exit When
traffic_rules_unavailable 30 The Space has no edge yet. Publish it once

sf rules test

Answer one request against the Space’s traffic rules, and print the first rule of each list that matches. The CLI evaluates the rules the way the edge does. It sends no request to the Space and changes nothing.

sf rules test <url> [--file <path>] [--method <value>] [--ip <value>] [--country <value>]
  [--asn <value>] [--user-agent <value>] [--referer <value>] [--ja3 <value>] [--ja4 <value>]
  [--header <name=value>]... [--cookie <name=value>]... [--space <value>]

Arguments

Argument What it is
<url> URL or path to answer, for example /wp-login.php. Required

Flags

Flag Default What it does
--file=<path> none Answer from this config file instead of the Space’s live rules
--method=<value> none HTTP method. With none, no method condition matches
--ip=<value> none Client address
--country=<value> none Two-letter country code
--asn=<value> none The client network’s ASN
--user-agent=<value> none User agent
--referer=<value> none The Referer header
--ja3=<value> none TLS JA3 fingerprint
--ja4=<value> none TLS JA4 fingerprint
--header=<name=value> none A request header. Repeatable
--cookie=<name=value> none A request cookie. Repeatable

Without --file, the command reads the enabled rules from listSpaceTrafficRules. A bare path is then tested against the Space’s first hostname. With --file, a bare path is tested against localhost.

Firewall rules never match the platform’s own transport paths, such as /__spacefast/health.php.

sf rules test /wp-login.php --country RU
sf rules test https://docs.example.com/admin/ --ip 203.0.113.7
sf rules test /api/orders --file spacefast.config.ts

Output

Answered from the space's live rules.
No host given; answering as docs.example.com.
firewall: block-logins block 403 at the edge, from overlay
cache-bypass: no rule matches

While rules are paused, the output adds Rules are paused, so the live space answers this request normally.

With --json, data is { request, source, paused, firewall, cacheBypass }. firewall and cacheBypass are each null or { name, kind, action, placement, origin }.

Errors

Code Exit When
validation_error 2 --header or --cookie is not name=value
validation_error 2 A rule in the --file config does not parse. Run sf rules validate
config_not_found 2 --file names a JSONC or JSON file that does not exist
config_invalid 2 The --file config is not valid JSON, or its firewall or cache keys have the wrong shape

sf rules validate

Check the rules a local config file declares against the rule grammar and the edge. It reports every problem with the field it is in. It writes nothing.

sf rules validate [--file <path>] [--space <value>]

Flags

Flag Default What it does
--file=<path> the config file in this directory Config file to read

Without --file, the command reads the first config file it finds in the current directory: spacefast.config.ts, then sf.jsonc and its aliases. The check runs against the selected Space’s edge.

sf rules validate
sf rules validate --file build/spacefast.config.ts

Output

<file> declares <n> traffic rule(s) the edge accepts., or <file> declares no traffic rules. when the file has none.

With --json, data is { valid, issues }, the validateSpaceTrafficRules response.

Errors

Code Exit When
traffic_rules_invalid 2 One or more rules have problems. details.issues lists each { path, message }, for example firewall[0].match.country
config_not_found 2 No config file in this directory, or --file names a JSONC or JSON file that does not exist
config_invalid 2 The config is not valid JSON, or its firewall or cache keys have the wrong shape
traffic_rules_unavailable 30 The Space has no edge yet. Publish it once

Last updated on

Was this page helpful?