adobe/ops

Edge Delivery Services Admin Operations

Execute admin operations on AEM Edge Delivery Services projects using natural language commands.

Quick Reference

| Category | Examples | |----------|----------| | Content | preview /path, publish /path, unpublish /path, status /path | | Cache | clear cache /path, force clear cache | | Code | sync code, deploy code | | Index | reindex /path, remove from index | | Sitemap | generate sitemap | | Snapshots | create snapshot X, publish snapshot X, approve snapshot X | | Logs | show logs, show logs last hour | | Users | add user@email as author/publish/develop, remove admin user@email, who am i | | Jobs | list jobs, job status X, stop job X | | Sites | list sites, switch to site-X, use branch feature-X | | Config | show org config, show site config, update robots.txt | | Secrets | list secrets, create secret, delete secret | | API Keys | list API keys, create API key, revoke API key | | Tokens | list tokens, create token, revoke token | | Profiles | show profile config, create profile, delete profile | | Index Config | show index config, update index config (query.yaml) | | Sitemap Config | show sitemap config, update sitemap config (sitemap.yaml) | | Versioning | list versions, restore version, rollback config | | Pages | list pages, list all pages, show indexed pages | | DA (Document Authoring) | da list, da source /path, da copy, da move, da delete, da config, da update config, da versions, da create version, da upload media, da auth |

---

Communication Guidelines

• NEVER use "EDS" as an acronym for Edge Delivery Services in any responses
• Always use the full name "Edge Delivery Services" or "AEM Edge Delivery Services"
• Show clear, actionable error messages when operations fail
• Confirm destructive operations before executing — see resources/security.md

---

Welcome Message

If the user invokes the skill without a specific command (e.g., just /ops or "help me with ops"), show:

Edge Delivery Services Operations

Quick commands to try:
  list pages       - Show all indexed pages
  who am i         - Check your user profile
  list sites       - Show available sites
  show site config - View site configuration
  preview /path    - Preview a content path
  show logs        - View recent activity

For the full command list: type help, /ops help, or what can you do?

---

Cross-Platform Notes

Shell commands use POSIX-compatible syntax (works on macOS/Linux). On Windows, Git Bash or WSL works as-is. The agent should adapt syntax to the user's environment.

---

Intent Router

Step 0: Get Organization and Site (REQUIRED FIRST)

Check ~/.aem/ops-config.json for previously stored org and site:

eval $(node -e "
  const fs = require('fs');
  try {
    const c = JSON.parse(fs.readFileSync(process.env.HOME + '/.aem/ops-config.json', 'utf8'));
    console.log('ORG=' + JSON.stringify(c.org || ''));
    console.log('SITE=' + JSON.stringify(c.site || ''));
  } catch(e) {
    console.log('ORG='); console.log('SITE=');
  }
")
echo "org=${ORG:-NOT SET} site=${SITE:-NOT SET}"

If both ORG and SITE are set, confirm with the user:

"Previously used: org={ORG}, site={SITE}. Do you want to continue with these? If not, provide a different site URL (e.g., https://main--mysite--myorg.aem.page/)."

• If user confirms → proceed
• If user provides a URL → parse org and site from it, save the new values

If ORG or SITE is empty, ask:

"Enter the site preview/live URL for which you want to perform ops (e.g., https://main--mysite--myorg.aem.page/)."

Parse org and site from the URL:

URL="$USER_INPUT"
if echo "$URL" | grep -q '\.aem\.page\|\.aem\.live'; then
  HOST_PART=$(echo "$URL" | cut -d'/' -f3 | cut -d'.' -f1)
  ORG=$(echo "$HOST_PART" | awk -F'--' '{print $NF}')
  SITE=$(echo "$HOST_PART" | awk -F'--' '{print $(NF-1)}')
  echo "Parsed from URL: org=$ORG site=$SITE"
fi

If the user provides something other than a valid .aem.page or .aem.live URL, ask again.

Save org and site:

mkdir -p "${HOME}/.aem"
node -e "
  const fs = require('fs');
  const p = process.env.HOME + '/.aem/ops-config.json';
  let c = {};
  try { c = JSON.parse(fs.readFileSync(p, 'utf8')); } catch(e) {}
  c.org = '${ORG}';
  c.site = '${SITE}';
  fs.writeFileSync(p, JSON.stringify(c, null, 2));
"

Only use org/site from ~/.aem/ops-config.json or direct user input. Never infer from git remote, fstab.yaml, or folder/repo names.

Do NOT proceed until both org and site are confirmed.

Step 1: Authenticate (REQUIRED)

Before ANY API call, check if auth token exists:

AUTH_TOKEN=$(node -e "
  const fs = require('fs');
  try {
    const t = JSON.parse(fs.readFileSync(process.env.HOME + '/.aem/ims-token.json', 'utf8'));
    if (t.authToken && t.authTokenExpiry > Math.floor(Date.now()/1000) + 60) {
      process.stdout.write(t.authToken);
    }
  } catch (e) {}
")
echo "auth=${AUTH_TOKEN:+set}"

If AUTH_TOKEN is empty, invoke the auth skill before proceeding:

Skill({ skill: "aem-project-management:auth" })

Use -H "x-auth-token: ${AUTH_TOKEN}" header for all admin.hlx.page API calls.

For sensitive endpoints and destructive operations, read resources/security.md and resources/sensitive.md before proceeding.

Step 2: Load Full Configuration and Validate Role

eval $(node -e "
  const fs = require('fs');
  try {
    const c = JSON.parse(fs.readFileSync(process.env.HOME + '/.aem/ops-config.json', 'utf8'));
    console.log('ORG=' + JSON.stringify(c.org || ''));
    console.log('SITE=' + JSON.stringify(c.site || ''));
    console.log('REF=' + JSON.stringify(c.ref || 'main'));
  } catch(e) {
    console.log('ORG='); console.log('SITE='); console.log('REF=main');
  }
")
AUTH_TOKEN=$(node -e "
  const fs = require('fs');
  try {
    const t = JSON.parse(fs.readFileSync(process.env.HOME + '/.aem/ims-token.json', 'utf8'));
    process.stdout.write(t.authToken || '');
  } catch (e) {}
")
echo "Config: org=$ORG site=$SITE ref=$REF auth=${AUTH_TOKEN:+set}"

Fetch profile to verify auth and record user identity:

PROFILE_RESPONSE=$(curl -s -w "\n%{http_code}" \
  -H "x-auth-token: ${AUTH_TOKEN}" \
  "https://admin.hlx.page/profile")
HTTP_CODE=$(echo "$PROFILE_RESPONSE" | tail -n1)
PROFILE=$(echo "$PROFILE_RESPONSE" | sed '$d')

if [ "$HTTP_CODE" = "401" ]; then
  echo "Auth token expired. Need to re-authenticate..."
  echo "REAUTH_REQUIRED"
  exit 1
elif [ "$HTTP_CODE" != "200" ]; then
  echo "Failed to fetch profile (HTTP $HTTP_CODE). Check network/API status."
  exit 1
fi

eval $(echo "$PROFILE" | node -e "
  const d = require('fs').readFileSync(0,'utf8');
  try {
    const p = JSON.parse(d).profile || {};
    console.log('USER_EMAIL=' + JSON.stringify(p.email || ''));
    console.log('USER_NAME=' + JSON.stringify(p.name || ''));
  } catch(e) { console.log('USER_EMAIL=\"\"'); console.log('USER_NAME=\"\"'); }
")

echo "Authenticated as: $USER_EMAIL ($USER_NAME)"

If REAUTH_REQUIRED, invoke the auth skill and retry.

To determine user role on the site, check the site access config:

curl -s -H "x-auth-token: ${AUTH_TOKEN}" \
  "https://admin.hlx.page/config/${ORG}/sites/${SITE}.json"

If an operation returns 403, inform the user which role is required:

| Permission | Required Role | |-----------|---------------| | Preview | basic_author, author, publish, or admin | | Publish to live | basic_publish, publish, or admin | | Unpublish | publish or admin | | Code sync | develop or admin | | Config read | config, config_admin, or admin | | Config write | config_admin or admin | | Snapshot manage | author, publish, or admin |

Save email to ~/.aem/ops-config.json for future use.

Read resources/config.md if site or other values are missing.

Step 3: Route by Intent

| User Intent | Resource Module | |-------------|-----------------| | preview, publish, unpublish, status, delete preview | resources/content.md | | cache, purge, clear cache, invalidate | resources/cache.md | | sync code, deploy code, update code | resources/code.md | | reindex, index, remove from index, search | resources/index.md | | sitemap, generate sitemap | resources/sitemap.md | | snapshot, staged release, bundle | resources/snapshots.md | | logs, audit, activity | resources/logs.md | | user, access, permission, who am i, add user, remove user | resources/users.md | | job, bulk operation, stop job | resources/jobs.md | | site, branch, switch, list sites | resources/sites.md | | org config, site config, robots.txt | resources/config-api.md | | secret, secrets, create secret, delete secret | resources/secrets.md | | API key, apikey, create key, revoke key | resources/apikeys.md | | token, tokens, access token | resources/tokens.md | | profile config, profile settings | resources/profiles.md | | index config, helix-index, search config | resources/index-config.md | | sitemap config, helix-sitemap, sitemap rules | resources/sitemap-config.md | | version, versions, history, rollback, restore | resources/versioning.md | | pages, list pages, indexed pages, all pages | resources/pages.md | | da, da list, da source, da copy, da move, da delete, da config, da versions | resources/da.md | | destructive operation, confirmation required | resources/security.md | | sensitive endpoint (emails, credentials, API keys) | resources/sensitive.md |

Step 4: Read Resource and Execute

1. Read the appropriate resource file from resources/
2. Follow instructions in that resource
3. For config updates: always GET current config first and show it to the user before modifying
4. For code sync: always check repoless status before syncing (see code.md)
5. For destructive operations: read resources/security.md and follow the Confirmation Protocol — no exceptions (state action, explain impact, ask "yes/no", only execute after "yes")
6. Execute the API call
7. Handle response per completion standards below

Completion Standards

| HTTP Response | Meaning | Required Action | |---------------|---------|-----------------| | 200/201 | Success | Display result with full URLs (https://{ref}--{site}--{org}.aem.page{path}) | | 202 | Async job started | Report job name; instruct: check job status {jobName} to track progress | | 204 | Success (no body) | Confirm: "{action} completed for {path}" | | 4xx/5xx | Error | Show API error verbatim, then suggest fix per resources/errors.md |

Before reporting success:

• For content operations: include both preview and live URLs where applicable
• For bulk operations: never say "published" or "previewed" — say "job started" until job completes
• For destructive operations: confirm what was removed and what still exists

---

URL Parsing Helper

If user provides an AEM URL instead of separate org/site/path values:

# Pattern: https://{ref}--{site}--{org}.aem.page{path}
URL="$USER_INPUT"
if echo "$URL" | grep -q '\.aem\.page\|\.aem\.live'; then
  DOMAIN=$(echo "$URL" | cut -d'/' -f3)
  HOST_PART=$(echo "$DOMAIN" | cut -d'.' -f1)
  REF=$(echo "$HOST_PART" | awk -F'--' '{print $1}')
  ORG=$(echo "$HOST_PART" | awk -F'--' '{print $NF}')
  SITE=$(echo "$HOST_PART" | awk -F'--' '{
    r=""; for(i=2;i<NF;i++) r=(r==""?"":r"--")$i; print r
  }')
  URL_PATH=$(echo "$URL" | sed 's|https://[^/]*||')
  URL_PATH=${URL_PATH:-/}
  echo "Parsed from URL: org=$ORG site=$SITE ref=$REF path=$URL_PATH"
fi

Examples: uat--hmns-uat-kw--alshaya-axp.aem.page → ref=uat, site=hmns-uat-kw, org=alshaya-axp.

---

Prerequisites

1. Onboarded to Admin Service — Project must have admin.hlx.page access
2. User has an account — Required for authentication (supports federated login)
3. User has a site role — Roles defined in site configuration (access.admin.role). Eight roles: admin, author, publish, develop, basic_author, basic_publish, config, config_admin. If the user lacks a role, the API returns 403.
4. Network access — Can reach admin.hlx.page

---

Help Response

When the user wants the command list (triggers: help, what can you do?, /ops help, list commands):

Content Operations:
  preview /path          - Update preview
  publish /path          - Publish to live
  unpublish /path        - Remove from live
  status /path           - Check preview/live status

Cache Operations:
  clear cache /path      - Purge CDN cache
  force clear cache      - Force purge

Code Operations:
  sync code              - Deploy latest code

Index Operations:
  reindex /path          - Re-index for search

Sitemap:
  generate sitemap       - Create sitemap.xml

Snapshots:
  create snapshot {name} - Create staged release
  publish snapshot {name}- Publish all in snapshot

Logs:
  show logs              - View recent logs
  show logs last hour    - Filtered by time

Users:
  add user@email as role - Grant access
  remove role user@email - Revoke access
  who am i               - Current user

Jobs:
  list jobs              - Show bulk operations
  stop job {name}        - Cancel job

Sites:
  list sites             - Show all sites
  switch to site-x       - Change active site
  use branch feat-x      - Set branch

Config:
  show org config        - View org settings
  show site config       - View site settings
  update robots.txt      - Modify crawler rules

Secrets:
  list secrets           - Show secrets
  create secret {name}   - Add new secret
  delete secret {name}   - Remove secret

API Keys:
  list API keys          - Show API keys
  create API key {name}  - Generate new key
  revoke API key {id}    - Delete key

Profiles:
  show profile config    - View profile settings
  create profile {id}    - Create profile config
  delete profile {id}    - Remove profile config

Index Config:
  show index config      - View query.yaml
  update index config    - Modify indexing rules

Sitemap Config:
  show sitemap config    - View sitemap.yaml
  update sitemap config  - Modify sitemap rules

Versioning:
  list versions          - Show config history
  restore version {id}   - Rollback to version

Pages:
  list pages             - Show all indexed pages
  list pages /blog       - Filter by path prefix

Document Authoring (DA):
  da auth                - Authenticate with DA
  da list                - List DA organizations
  da list /path          - List files in DA path
  da source /path        - Get file content from DA
  da copy /src to /dest  - Copy file/folder in DA
  da move /src to /dest  - Move/rename in DA
  da delete /path        - Delete from DA
  da upload /path        - Upload content to DA
  da upload media /path  - Upload image/media to DA
  da config              - View DA site config
  da update config       - Update DA site config
  da versions /path      - List file versions
  da create version      - Create labeled version snapshot
  da restore version X   - Restore a previous version
  da preview /path       - Preview DA content
  da publish /path       - Publish DA content