@adobe/mysticat-cli

Command-line interface for SpaceCat. Built for humans, AI agents, and CI/CD pipelines.

Install

npm install -g @adobe/mysticat-cli

Requires Node.js >= 20.

Quick start

# Authenticate via browser (opens Adobe IMS)
mysticat login

# Check login status
mysticat status

# List sites
mysticat site list
mysticat site list --live --limit 10
mysticat site list --all          # page through every site

# Get site details
mysticat site get https://example.com

Commands

| Command | Description | |---------|-------------| | mysticat login | Authenticate via Adobe IMS (browser or headless) | | mysticat logout | Clear stored tokens | | mysticat status | Show login status, environment, and token expiry | | mysticat auth token | Print or copy session token | | mysticat site list | List sites with optional filters | | mysticat site get <url> | Get site information by URL | | mysticat config get [key] | Show configuration | | mysticat config set <key> <value> | Set a configuration value |

All data commands support --json for machine-readable output.

site list pagination. site list pages through the SpaceCat /sites endpoint with an opaque cursor under the hood; --limit caps how many rows are shown (default 25, must be ≥ 1) and --all fetches every site. Because the cursor API does not return a count, pagination.total in --json output is an exact count only when the server returned its final page (collection finished), and null whenever collection stopped with pages still outstanding. Under --live (a client-side filter) total counts the live rows in the listing, not the tenant's total site count. pagination.limit echoes the requested display cap and is not applied under --all. --all collects all rows in memory before printing.

The paginated endpoint returns the full, unfiltered result set: sites belonging to orgs that the older non-paginated /sites path used to exclude now appear in the listing. (Per adobe/spacecat-api-service#2497 that exclusion was a response-size optimization, not an access boundary — the session's authorization scope is unchanged.)

Authentication

IMS client credentials (one-time setup)

Interactive browser login needs the IMS OAuth client secret, which is not committed to source. Its system of record is Vault (dx_mysticat/mysticat-cli/{stage,prod}). Pull it into ~/.mysticat/.env once:

scripts/pull-ims-secret.sh

The script logs you into Vault (Adobe VPN + Okta required) and writes the stage and prod client credentials to ~/.mysticat/.env, which the CLI loads at startup. To set it up by hand instead, cp .env.example .env and fill in the secrets, or export the MYSTICAT_*_IMS_CLIENT_SECRET variables directly. The non-secret client IDs ship in the committed .env.defaults.

The headless --token login below needs no client credentials — it accepts an already-minted IMS token.

Browser login (interactive)

mysticat login
mysticat login --env stage
mysticat login --product LLMO

Opens a browser for Adobe IMS OAuth (PKCE). The CLI starts a local callback server, receives the authorization code, exchanges it for tokens, and stores them in ~/.mysticat/tokens.json.

Headless login (CI/CD, agents)

echo "$IMS_TOKEN" | mysticat login --token

Accepts an IMS access token on stdin and exchanges it with SpaceCat for a session JWT.

Token resolution order

For authenticated commands, tokens are resolved in this order:

1. MYSTICAT_TOKEN env var (raw session JWT)
2. MYSTICAT_TOKEN_FILE env var (path to file containing session JWT)
3. Stored session token (from ~/.mysticat/tokens.json)
4. Auto-refresh via stored IMS access token
5. Auto-refresh via IMS refresh token grant

Using tokens in scripts

# Use session token directly
curl -H "Authorization: Bearer $(mysticat auth token)" https://spacecat.experiencecloud.live/api/sites

# Copy to clipboard
mysticat auth token --copy

# Get the IMS access token instead
mysticat auth token --ims

Configuration

# Set default environment
mysticat config set env stage

# Set default product
mysticat config set product LLMO

# View current config
mysticat config get

Configuration is stored in ~/.mysticat/config.json. Per-command --env flags override the default.

Environments

| Name | API | IMS | |------|-----|-----| | prod (default) | spacecat.experiencecloud.live | ims-na1.adobelogin.com | | stage | spacecat-stage.experiencecloud.live | ims-na1-stg1.adobelogin.com | | dev | spacecat-dev.experiencecloud.live | ims-na1-stg1.adobelogin.com |

Environment variables

| Variable | Purpose | |----------|---------| | MYSTICAT_TOKEN | Session JWT - bypasses token store | | MYSTICAT_TOKEN_FILE | Path to file containing session JWT | | MYSTICAT_CONFIG_DIR | Override config directory (default: ~/.mysticat) | | MYSTICAT_STAGE_IMS_CLIENT_ID / _SECRET | IMS client for dev + stage (secret from Vault via scripts/pull-ims-secret.sh) | | MYSTICAT_PROD_IMS_CLIENT_ID / _SECRET | IMS client for prod (secret from Vault via scripts/pull-ims-secret.sh) | | MYSTICAT_IMS_CLIENT_ID / MYSTICAT_IMS_CLIENT_SECRET | Global IMS client override (wins for every env) | | MYSTICAT_TIMEOUT | API request timeout in ms (default: 30000) | | DEBUG=mysticat:* | Enable debug logging |

Development

git clone [email protected]:adobe/mysticat-cli.git
cd mysticat-cli
npm install

# Run tests with coverage
npm test

# Lint
npm run lint

# Run CLI locally
./bin/run.js login
./bin/run.js site list --json

Project structure

src/
  commands/           # oclif command classes
    auth/token.js     # Print/copy tokens
    config/get.js     # Show config
    config/set.js     # Set config
    login.js          # Browser and headless login
    logout.js         # Clear tokens
    site/get.js       # Get site by URL
    site/list.js      # List sites
    status.js         # Login status
  hooks/init/         # oclif lifecycle hooks
  lib/
    api/client.js     # SpaceCat API client
    auth/             # IMS OAuth, token storage, resolution
    config/           # Environment config, persistent settings
    output/           # Output formatting
test/                 # Mirrors src/ structure

Releasing

Releases are fully automated via semantic-release on merge to main. Use conventional commits:

• feat: - new feature (minor version bump)
• fix: - bug fix (patch version bump)
• feat!: or BREAKING CHANGE: - breaking change (major version bump)

npm publishing uses trusted publishing via OIDC - no stored npm tokens required.

License

Apache-2.0