Skip to content
WebShield Docs

Command-line client (CLI)

Install and use the webshield CLI to manage domains, DNS records, edge settings and publish static sites from the terminal or CI.

webshield is the official command-line client for the WebShield API. It manages domains and DNS records, edge settings of proxied hosts, publishes static sites (including incremental publishing from CI), and shows statistics and billing usage.

Source code and releases: github.com/webshieldpro/webshield-cli.

The installer detects your OS and architecture, downloads the latest release, verifies the SHA-256 checksum and installs the binary to ~/.local/bin:

Terminal window
curl -fsSL https://raw.githubusercontent.com/webshieldpro/webshield-cli/main/install.sh | sh

Prebuilt binaries are available for Linux (x86_64, aarch64 — static, no dependencies) and Windows on the releases page. You can also build from source with Rust:

Terminal window
git clone https://github.com/webshieldpro/webshield-cli
cd webshield-cli
cargo build --release
mv target/release/webshield ~/.local/bin/

Each release archive ships completion scripts; the binary can also generate them for bash, zsh, fish, PowerShell, elvish and nushell:

Terminal window
# bash
webshield completion bash > ~/.local/share/bash-completion/completions/webshield
# zsh (the target dir must be on $fpath)
webshield completion zsh > ~/.zfunc/_webshield
# fish
webshield completion fish > ~/.config/fish/completions/webshield.fish

The CLI uses a personal API token (wsk_…). Create one in the control panel under Settings → API tokens with the scopes you need — see API tokens. For CI, prefer a narrow token bound to a single domain or site.

Terminal window
webshield auth login # prompts for the token and saves it to a profile
webshield auth status # shows the active profile and verifies access

Alternative ways to pass the token: the --token flag or the WS_TOKEN environment variable (convenient in CI). Profiles are stored in ~/.config/webshield/config.toml; several profiles are supported via --profile (or WS_PROFILE), like in aws or gh.

Terminal window
webshield domains list # your domains and delegation status
webshield domains add example.com # add a domain (imports existing records by scanning)
webshield domains add example.com --import none
webshield domains check example.com # check delegation to WebShield nameservers
webshield domains remove example.com

The domain stays at your DNS provider, and names are connected with records (details in Connect without changing nameservers):

Terminal window
webshield domains add example.com --external
webshield hosts add www.example.com --domain example.com --origin 203.0.113.10 # prints the records
webshield hosts verify www.example.com # after the _acme-challenge record: confirmation and certificate
webshield hosts list # status, certificate, whether traffic flows through us
webshield hosts records www.example.com # the records again
webshield hosts add blog.example.com --domain example.com --mode static
webshield proxy set www.example.com --domain example.com --origin 203.0.113.20 # change the server
webshield hosts remove www.example.com
Terminal window
webshield dns list example.com
webshield dns list example.com --type A
webshield dns add example.com www A 203.0.113.10 # add a value to the set
webshield dns set example.com @ A 203.0.113.10 # make the set exactly this value
webshield dns remove example.com www A 203.0.113.10 # remove a single value
webshield dns remove example.com www TXT # remove the whole record set
webshield dns add example.com www CNAME foo.example.com # trailing dot added automatically
webshield dns add example.com @ MX "10 mail.example.com" --ttl 3600

Semantics for multi-value types (A, AAAA, TXT, MX): add appends values to the existing set, set makes the set exactly the given values, remove deletes only the listed values (without values — the whole set). CNAME/NS are single-valued and always replaced.

Terminal window
webshield dns dnssec status example.com # DS records for the registrar
webshield dns dnssec enable example.com
webshield dns dnssec disable example.com # blocked while a DS is live in the parent zone

See DNSSEC for the delegation-side steps.

Terminal window
webshield apps list
webshield apps deploy --project shop --app web # pack the directory, upload, wait until live
webshield apps deploy --url https://example.com/app.tar.gz --project shop --app web
webshield apps deployments --project shop --app web
webshield apps redeploy 42 # roll back to deployment #42
webshield apps logs --project shop --app web -f # follow the log
webshield apps db create db --size 2 # a Postgres database in the project
webshield apps db restore db --as db2 --time 2026-10-21T15:00:00+03:00 # into a new database; no --time — latest state
webshield apps kv create cache --memory 128 # a Valkey store
webshield apps env set DATABASE_URL='${{db.url}}' REDIS_URL='${{cache.url}}' --redeploy
printf %s "$STRIPE_KEY" | webshield apps env set STRIPE_KEY # value from stdin
webshield apps env list # names only; values with --values
webshield apps env unset OLD_FLAG
webshield apps db list; webshield apps kv delete cache
webshield apps d1 migrate --app api app-db # a function: D1 migrations from the project directory
webshield apps d1 execute --app api app-db --command "SELECT 1"
webshield apps kv import --app api CACHE keys.json # function KV keys, Wrangler bulk format
webshield apps window --app api # from which moment function data can be returned
webshield apps restore --app api --time 2026-10-21T15:00:00+03:00
webshield apps operations --app api # recent data operations of the function
webshield apps balance # available balance and prices
webshield apps usage --project shop # project spending this month, by day
webshield apps cap 500 --project shop # monthly cap; off removes it

Names are optional: the commands read the project and the app from webshield.toml in the directory (--dir, the current one by default). Put a ${{…}} reference in single quotes, or the shell will try to expand it itself. Without --redeploy variables apply from the next deployment. deploy waits until the app is live and exits non-zero on failure. More in Apps and Functions, deploying from CI — the guide.

Terminal window
webshield sites list
webshield sites create www.example.com --domain example.com
webshield sites publish www.example.com --dir ./public # incremental publish
webshield sites publish --site-id 6 --dir ./public # by id (narrow sites:publish tokens)
webshield sites publish www.example.com --dir ./public --dry-run # show the plan only
webshield sites publish-from-bucket www.example.com --bucket web --path public/ # from your S3 bucket
webshield sites files www.example.com

publish-from-bucket publishes the site straight from one of your own object-storage buckets (upload it there with any S3 tool first). The command starts the async publish and waits until it finishes.

publish computes a stateless diff against the server (by content hash), uploads only changed files, deletes vanished ones and atomically publishes a new version — safe to run from CI on every build.

A minimal GitHub Actions (Gitea Actions, Forgejo Actions) step:

- name: Publish site
env:
WS_TOKEN: ${{ secrets.WS_PUBLISH_TOKEN }}
run: |
curl -fsSL https://raw.githubusercontent.com/webshieldpro/webshield-cli/main/install.sh | sh
~/.local/bin/webshield sites publish www.example.com --dir ./public

The same job for GitLab CI (WS_TOKEN is a CI/CD variable with Masked and Protected ticked):

publish:
script:
- curl -fsSL https://raw.githubusercontent.com/webshieldpro/webshield-cli/main/install.sh | sh
- ~/.local/bin/webshield sites publish www.example.com --dir ./public

More on hosting modes and CI tokens — Hosting static sites.

Terminal window
webshield proxy list
webshield proxy get app.example.com
webshield proxy set app.example.com --domain example.com --ssl true --bot-protection true
webshield proxy set old.example.com --domain example.com \
--mode redirect --redirect-target example.com
webshield proxy set shop.example.com --domain example.com --html-cache true
webshield proxy purge-cache app.example.com
webshield proxy remove app.example.com

proxy set creates the host config or partially updates an existing one; boolean flags are sent only when specified, other settings stay untouched.

purge-cache drops everything we cached for the host — handy at the end of a deploy if files changed under the same names. See CDN and protection for details.

Terminal window
webshield stats summary example.com --range 7d # traffic/requests summary
webshield stats bans example.com # active bans and challenges
webshield billing balance
webshield billing usage example.com # traffic vs the plan limit
webshield billing tariffs example.com

Every command supports machine-readable output:

Terminal window
webshield -o json domains list | jq -r '.[].name'

Interface language is selected with --lang en|ru (or WS_LANG); by default it follows the system locale. --yes skips confirmation prompts for destructive operations.