Update to Fastly Agent Toolkit

{
  "description": "Executes Fastly CLI commands for managing CDN services, Compute deploys, and edge infrastructure. Use when running `fastly` CLI commands, creating or managing Fastly services from the terminal, deploying Fastly Compute applications, managing backends/domains/VCL snippets via command line, purging cache, configuring log streaming, setting up TLS certificates, managing KV/config/secret stores, checking service stats, authenticating with Fastly SSO, or working with fastly.toml. Also applies when working with Fastly service IDs in CLI context, or with `fastly service`, `fastly compute`, `fastly auth`, or any Fastly CLI subcommand. Covers service CRUD, version management, autocloning, and troubleshooting common CLI errors.",
  "included_files": [
    {
      "relative_path": "references/auth.md",
      "size_in_bytes": 9267
    },
    {
      "relative_path": "references/compute.md",
      "size_in_bytes": 15111
    },
    {
      "relative_path": "references/logging.md",
      "size_in_bytes": 11132
    },
    {
      "relative_path": "references/ngwaf.md",
      "size_in_bytes": 18746
    },
    {
      "relative_path": "references/notifications.md",
      "size_in_bytes": 4338
    },
    {
      "relative_path": "references/services.md",
      "size_in_bytes": 27954
    },
    {
      "relative_path": "references/stats.md",
      "size_in_bytes": 4105
    },
    {
      "relative_path": "references/stores.md",
      "size_in_bytes": 14291
    },
    {
      "relative_path": "references/tls.md",
      "size_in_bytes": 11706
    },
    {
      "relative_path": "references/troubleshooting.md",
      "size_in_bytes": 3981
    }
  ],
  "name": "fastly-cli",
  "skill_md_contents": "---\nname: fastly-cli\ndescription: \"Executes Fastly CLI commands for managing CDN services, Compute deploys, and edge infrastructure. Use when running `fastly` CLI commands, creating or managing Fastly services from the terminal, deploying Fastly Compute applications, managing backends/domains/VCL snippets via command line, purging cache, configuring log streaming, setting up TLS certificates, managing KV/config/secret stores, checking service stats, authenticating with Fastly SSO, or working with fastly.toml. Also applies when working with Fastly service IDs in CLI context, or with `fastly service`, `fastly compute`, `fastly auth`, or any Fastly CLI subcommand. Covers service CRUD, version management, autocloning, and troubleshooting common CLI errors.\"\n---\n\n## Trigger and scope\n\nCRITICAL: many subcommands have unintuitive paths (e.g. `fastly domain create` fails with 403, correct is `fastly service domain create`; logging is under `fastly service logging`; alerts under `fastly service alert`; rate limits under `fastly service rate-limit`).\n\nCovers: services, backends, domains, VCL snippets, cache purging, Compute/WASM deploys, log streaming (S3/Datadog/Splunk/Kafka/25+ providers), NGWAF/WAF, TLS/mTLS, KV/config/secret stores, stats, alerts, rate limiting, ACLs, and auth tokens.\n\n# Fastly CLI Overview\n\n## Prerequisites\n\nRequires the `fastly` CLI; API operations also need network access to Fastly.\nFor installation, see <https://www.fastly.com/documentation/reference/cli/>.\nJSON examples also need `jq`; origin checks use `curl` and `openssl`.\nCompute builds need the project's language toolchain and dependencies.\n\nUse credentials already configured in the user's local CLI or environment.\nIf authentication is missing, have the user complete `fastly auth login --sso` locally or configure `FASTLY_API_TOKEN` outside chat.\nNever ask for an API key in chat, print a token, or enable shell tracing on authenticated commands.\n\n## References\n\n| Topic          | File                                            | Use when...                                                                              |\n| -------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------- |\n| Authentication | [auth.md](references/auth.md)                   | Login, stored tokens, service auth, CI/CD auth setup                                     |\n| Compute        | [compute.md](references/compute.md)             | Building/deploying edge applications, local dev server                                   |\n| Services       | [services.md](references/services.md)           | Service CRUD, backends, domains, ACLs, dictionaries, VCL, purging, rate limiting         |\n| Logging        | [logging.md](references/logging.md)             | Log streaming to S3, GCS, Datadog, Splunk, Kafka, 25+ providers                          |\n| NGWAF          | [ngwaf.md](references/ngwaf.md)                 | Next-Gen WAF workspaces, IP/country lists, rules, signals, thresholds, alerts            |\n| Notifications  | [notifications.md](references/notifications.md) | Slack/PagerDuty/webhook integrations, audit log event mappings                            |\n| Stats          | [stats.md](references/stats.md)                 | Which `fastly stats` subcommand takes which flag, and where the two flag sets diverge    |\n| Stores         | [stores.md](references/stores.md)               | KV Stores, Config Stores, Secret Stores, resource links                                  |\n| TLS            | [tls.md](references/tls.md)                     | Platform TLS, Let's Encrypt subscriptions, custom certs, mutual TLS                      |\n\nFor endpoint choice, unit and window conventions and worked queries, use the **fastly-stats** skill.\n\n## Command Structure\n\n```\nfastly <command> <subcommand> [flags]\n```\n\n### Top-Level Commands\n\n| Category     | Commands                                                                                |\n| ------------ | --------------------------------------------------------------------------------------- |\n| **Compute**  | `compute` - Build and deploy edge applications                                          |\n| **Services** | `service` - Manage CDN services, logging, backends, VCL, ACLs, purging                  |\n| **Security** | `ngwaf` - Web application firewall                                                      |\n| **TLS**      | `tls-subscription`, `tls-custom`, `tls-platform`, `tls-config` - Certificate management |\n| **Storage**  | `kv-store`, `config-store`, `secret-store` - Edge data stores                           |\n| **Auth**     | `auth` - Login, stored tokens, active token output, revocation; `auth-token` (deprecated) |\n| **Info**     | `stats`, `ip-list`, `pops`, `whoami` - Information queries                              |\n| **Notify**   | `integration` - Notification destinations; `audit-log event-mapping` - Event triggers   |\n| **Other**    | `dashboard`, `domain`, `dns`, `apisecurity`, `products`, `object-storage`, `tools`      |\n\n## Global Flags\n\nAvailable on most commands:\n\n```bash\n# Service targeting\n--service-id SERVICE_ID    # Target service by ID\n--service-name NAME        # Target service by name\n-s SERVICE_ID              # Short form\n\n# Version targeting (version-scoped commands like `fastly service domain/backend/...`)\n# NOTE: `fastly domain create` does NOT accept --version (it uses a different API)\n--version VERSION          # Specific version number\n--version active           # Currently active version\n--version latest           # Most recent version\n--version staged           # Currently staged version\n\n# Authentication\n--token TOKEN              # API token or stored token name (use 'default' for default)\n\n# Output (--json is per-command, not global)\n--verbose                  # Detailed output\n--quiet                    # Minimal output\n\n# Automation\n--accept-defaults          # Accept default values\n--auto-yes                 # Skip confirmations\n--non-interactive          # No prompts\n```\n\n## Key Patterns\n\n- Target by ID (`-s SERVICE_ID`) or name (`--service-name NAME`)\n- Version targeting: `--version active`, `--version latest`, `--version staged`, or `--version N`\n- Use `--autoclone` to auto-clone locked versions\n- Use `--json` for scripted output, `--non-interactive --accept-defaults` for CI/CD\n- JSON field names vary by command; inspect output before writing `jq` selectors.\n- `ActiveVersion` shape varies; prefer `--version active`, or parse with `jq -r '.ActiveVersion.Number // .ActiveVersion'`\n- CLI version is `fastly version` (not `fastly --version`)\n- POP/shield lookup is `fastly pops`; it has no `list` subcommand and no `--json`; use the `SHIELD` column value (not POP `CODE`) for `--shield`\n- Auth: `fastly auth login --sso` to login, or set `FASTLY_API_TOKEN` env var\n- For commands that need the active API token, use `$(fastly auth token)`; select a specific stored token with `$(fastly auth token --token TOKEN_NAME)`\n- `auth token` refuses terminal output, but agent-captured stdout may be non-terminal; never run it standalone or echo its result\n- Logging is under `service logging` (e.g. `fastly service logging s3 create`)\n- Config: use `fastly config --location` to find the platform-specific CLI config file; `fastly.toml` is the project manifest\n\n## Common Flag Examples\n\nThese are the flags that cause the most confusion. Copy-paste these patterns directly.\n\n### Autocloning (existing service versions)\n\n```bash\n# --autoclone automatically clones a locked version before making changes.\n# Without it, you get \"version is locked\" errors and waste time cloning manually.\nfastly service backend create --service-id $SID --version active --autoclone \\\n  --name my-origin --address origin.example.com --port 443 --use-ssl\n\nfastly service domain create --service-id $SID --version active --autoclone \\\n  --name cdn.example.com\n```\n\nPass `--autoclone` when creating, updating, or deleting backends, domains, snippets, VCL, conditions, headers, or other version-scoped resources on an existing service.\nFor a brand new service, configure the unlocked `--version 1` without `--autoclone`, then validate and activate once, as shown in the new-service workflow below.\n\n### Boolean flags (--use-ssl, --use-ssl is NOT --use-ssl true)\n\n```bash\n# CORRECT - boolean flags are bare, no value\nfastly service backend create --name origin --address example.com --port 443 --use-ssl\n\n# WRONG - do not pass a value to boolean flags\nfastly service backend create --name origin --address example.com --port 443 --use-ssl true\n```\n\nOther boolean flags that work the same way: `--auto-yes`, `--non-interactive`, `--verbose`, `--quiet`, `--autoclone`.\n\n### Domain creation (requires --name flag)\n\n```bash\n# CORRECT\nfastly service domain create --service-id $SID --version active --autoclone --name cdn.example.com\n\n# WRONG - domain is not a positional argument\nfastly service domain create --service-id $SID --version active cdn.example.com\n\n# WRONG - there is no -d flag\nfastly service domain create --service-id $SID --version active -d cdn.example.com\n```\n\n### Stats (historical and real-time)\n\n```bash\n# Historical stats by day for a date range (JSON output)\nfastly stats historical --service-id $SID --by day \\\n  --from \"2026-02-01\" --to \"2026-03-01\" --json\n\n# Real-time stats (last second)\nfastly stats realtime --service-id $SID --json\n```\n\nThe `--by` flag accepts: `day`, `hour`, `minute`. The `--from` and `--to` flags use quoted date strings. Use `--json` for JSON output on stats commands.\n\n## Propagation Delays\n\nChanges propagate across Fastly's network in seconds to minutes (up to 10 min for version activations, up to 5 min for TLS). Cache purges are 1-2 seconds. Retry with backoff when verifying changes.\n\n**New service activation sequence**: After activating a brand new service, expect 500 \"Domain Not Found\" for 10-60 seconds while the domain propagates to edge POPs. This is normal — do not change configuration. Wait and retry. After version updates (e.g., fixing backend settings), allow 15-30 seconds for the new version to propagate.\n\n## KV Store Gotchas\n\n- **Link before use**: A KV store must be linked to a service version before Compute code can access it. Use `fastly kv-store create` then `fastly service resource-link create --resource-id STORE_ID --service-id $SID --version active --autoclone`.\n- **Eventual consistency**: Read-after-write is eventually consistent. A key you just wrote may not be readable for a few seconds. Do not rely on immediate read-back in scripts; add a short delay or retry loop.\n- **Entry size limit**: Individual KV store entries are limited to 25 MB. Plan accordingly for large values.\n- **Listing stores**: `fastly kv-store list` lists all stores on the account, not per-service. Use `fastly service resource-link list` to see which stores are linked to a given service.\n\n## Host Header Override Pattern\n\nWhen the origin hostname differs from the desired Host header (e.g., origin is `example.com` but you want to send `Host: download.example.com`), use `--override-host` on the backend:\n\n```bash\nfastly service backend create --service-id $SID --version 1 \\\n  --name my-origin --address example.com --port 443 --use-ssl \\\n  --override-host download.example.com \\\n  --ssl-cert-hostname example.com --ssl-sni-hostname example.com\n```\n\nThe `--override-host` value is the Host header sent to the origin. The `--ssl-cert-hostname` and `--ssl-sni-hostname` must match the origin's TLS certificate (usually the `--address` value). Getting these backwards causes 503 errors.\n\n## Service List Completeness\n\nWhen enumerating services (e.g., for bandwidth stats), use `fastly service list --json`.\nThe command follows API pagination internally and returns all pages unless you explicitly start from a later `--page`.\nServices with zero traffic still appear in the list, so loop over every returned service ID instead of relying on stats APIs that omit zero-traffic services.\n\n## New VCL Service Setup Workflow\n\nUse this sequence to stand up a new VCL caching service end-to-end. Each step includes a validation checkpoint.\n\n1. **Pre-flight** — verify the origin responds and check its TLS certificate SANs:\n\n   ```bash\n   curl -sI -H \"Host: DESIRED_HOST\" https://ORIGIN_ADDRESS/\n   echo | openssl s_client -connect ORIGIN_ADDRESS:443 -servername ORIGIN_ADDRESS 2>/dev/null | \\\n     openssl x509 -noout -text | grep -A1 \"Subject Alternative Name\"\n   ```\n\n   _Checkpoint: origin returns 200 and the backend `ssl-cert-hostname` matches the served cert. If no HTTPS SNI/cert combination validates but HTTP with that Host works, use `--port 80` or fix the origin cert; do not disable verification._\n\n2. **Create service** — note the service ID from the output:\n\n   ```bash\n   fastly service create --name \"my-service\" --non-interactive\n   ```\n\n3. **Add domain + backend on version 1** (do NOT use `--autoclone` or `--version latest` on a new service):\n\n   ```bash\n   fastly service domain create --service-id $SID --version 1 \\\n     --name my-service.global.ssl.fastly.net\n\n   fastly service backend create --service-id $SID --version 1 \\\n     --name origin --address ORIGIN_ADDRESS --port 443 --use-ssl \\\n     --override-host ORIGIN_ADDRESS \\\n     --ssl-cert-hostname ORIGIN_ADDRESS --ssl-sni-hostname ORIGIN_ADDRESS\n   ```\n\n4. **Validate version** before activating:\n\n   ```bash\n   fastly service version validate --service-id $SID --version 1\n   ```\n\n   _Checkpoint: validation returns success (no missing domain/backend errors)._\n\n5. **Activate**:\n\n   ```bash\n   fastly service version activate --service-id $SID --version 1\n   ```\n\n6. **Verify propagation** — wait 15-30s, then test with GET (not HEAD):\n\n   ```bash\n   curl -sS -D - -o /dev/null https://my-service.global.ssl.fastly.net/ | head -1\n   ```\n\n   _Checkpoint: 200 OK. If 500 \"Domain Not Found\", wait and retry (normal for 10-60s). If 503, check backend SSL settings._\n\nSee [services.md](references/services.md) for advanced workflows (custom domains with TLS, host header overrides, live service updates).\n\n## Troubleshooting\n\nSee [troubleshooting.md](references/troubleshooting.md) for the full list. Key pitfalls are covered inline above: SSL hostname flags (see Host Header Override Pattern), boolean flags and domain `--name` (see Common Flag Examples), `--autoclone` (see Key Patterns), and token safety (see Key Patterns).\n"
}