Public CLI reference

Searchlight CLI documentation

Searchlight is a private, token-gated search-intelligence workspace. The CLI package is public to download, but every API-backed command requires a server-issued scoped token. This page is written for AI agents and approved operators who need the current command surface quickly.

Package

@movermarketingai/searchlight-cli

Auth model

public install / token-gated API

Default target

searchlight.movermarketing.ai

Install

Install the package globally, then use mmai-searchlight. The shorter searchlight alias exists, but the longer binary avoids command-name collisions.

Copy local install commands

npm install -g @movermarketingai/searchlight-cli
mmai-searchlight setup
mmai-searchlight help

Rules for AI agents

Do not ask a user to paste raw Searchlight tokens into chat.
Use stdin, Keychain/password managers, or a 0600 token file for token storage.
Prefer --json for machine parsing and --dry-run before write operations.
Run `annotations sites --json` before guessing a site slug.
Treat every 401/403 as an authorization boundary, not a CLI bug.
Do not create standalone SEO tests; tests are derived from annotations.

Copyable agent onboarding prompt

Users can copy this prompt into an AI agent so the agent starts with the right docs, install command, and token-safety boundaries.

Copy agent instruction prompt

You are helping me use the Searchlight CLI.

Canonical docs:
- https://searchlight.movermarketing.ai/docs
- https://searchlight.movermarketing.ai/llms.txt

Install/check commands for my local terminal:
npm install -g @movermarketingai/searchlight-cli
mmai-searchlight setup
mmai-searchlight help

Authentication rules:
- Do not ask me to paste raw Searchlight tokens into chat.
- Guide me to store tokens with stdin, Keychain/password manager, or a 0600 token file.
- Use: mmai-searchlight auth store --token-stdin
- Validate with: mmai-searchlight auth check --json

Workflow rules:
- Prefer --json for machine-readable output.
- Use --dry-run before writes when available.
- Run mmai-searchlight annotations sites --json before guessing a site slug.
- Treat 401/403 as authorization boundaries.
- Do not create standalone SEO tests; Searchlight tests are annotation-derived.

Authentication

Approved users either create a CLI token inside Searchlight or receive one from an admin. Store it through stdin or a locked-down token file. Do not print or log token values.

Copy safe token setup commands

mmai-searchlight setup
read -rsp "Searchlight CLI token: " SEARCHLIGHT_TOKEN && echo
printf '%s' "$SEARCHLIGHT_TOKEN" | mmai-searchlight auth store --token-stdin
unset SEARCHLIGHT_TOKEN
mmai-searchlight auth check --json

Token precedence

SEARCHLIGHT_TOKEN
SEARCHLIGHT_WORKER_TOKEN
SEARCHLIGHT_TOKEN_FILE
~/.config/searchlight/token

Commands

The tables below describe the current command surface. Use --json for automation and --dry-run before write operations whenever available.

Auth

Configure local token storage and confirm the API accepts it.

Task	Command	Notes
setup	`mmai-searchlight setup`	Prints safe setup guidance.
store token	`mmai-searchlight auth store --token-stdin`	Writes the token file with mode 0600.
check token	`mmai-searchlight auth check --json`	Validates the current token.
show token path	`mmai-searchlight auth path --json`	Shows the token-file path without printing the token.
logout	`mmai-searchlight auth logout --yes`	Removes the stored token file.

Clients and sites

List sites or run higher-trust onboarding flows when your token allows it.

Task	Command	Notes
list clients	`mmai-searchlight clients list --json`	Lists configured Searchlight clients/sites.
add client	`mmai-searchlight clients add --name NAME --gsc-property PROPERTY --site-slug SITE --json`	Creates a mapped site when permitted.
import	`mmai-searchlight clients import-report-portal --dry-run --json`	Operator-oriented import preview.

Annotations

Record shipped work. Annotation writes create or update SEO test windows and basic metadata.

Task	Command	Notes
list sites	`mmai-searchlight annotations sites --json`	Returns site slugs visible to the token.
list annotations	`mmai-searchlight annotations list --site SITE --json`	Reads annotations for a site.
add annotation	`mmai-searchlight annotations add --site SITE --title TITLE --summary TEXT --scope specific --page https://www.example.com/affected-page/ --dry-run`	Preview a page-scoped annotation write.
add from file	`mmai-searchlight annotations add-from-annotate --site SITE --file annotation.txt --dry-run`	Uses an annotation-formatted local file.
update	`mmai-searchlight annotations update --site SITE --id ID --summary TEXT --dry-run`	Preview an annotation update.
delete	`mmai-searchlight annotations delete --site SITE --id ID --yes`	Deletes an annotation when allowed.

SEO tests

Read or refresh annotation-derived test state. The CLI does not create standalone tests.

Task	Command	Notes
list tests	`mmai-searchlight tests list --site SITE --json`	Reads test state for a site.
refresh tests	`mmai-searchlight tests refresh --site SITE --json`	Recalculates test metrics.
run tests	`mmai-searchlight tests run --site SITE --json`	Alias for refresh behavior.

Scopes and access model

Searchlight validates token hash, expiry, revocation, allowed sites, and scopes server-side. CLI command availability is not an authorization boundary.

Scope	Meaning
sites:read	List sites visible to the token.
annotations:read	Read annotations and attached test state.
annotations:create	Create annotations, derived test windows, and basic inferred metadata.
annotations:update	Update existing annotations. Grant sparingly.
annotations:delete	Delete annotations/tests. Avoid for routine workers.
content-runs:read	Read server-created content-run metadata.
content-runs:create	Internal API scope for full manifest ingestion; not exposed by the public CLI.
tests:read	Read annotation-derived SEO test state.
tests:run	Refresh test calculations for an allowed site.
*	Admin-equivalent API access. Avoid outside trusted automation.

Machine-readable outputs

For agent workflows, prefer JSON output and parse by field instead of scraping text. Use the discovery file for high-level context.

Copy JSON output commands

mmai-searchlight auth check --json
mmai-searchlight annotations sites --json
mmai-searchlight annotations list --site SITE --json
curl https://searchlight.movermarketing.ai/llms.txt

Troubleshooting

Problem	Next step
No Searchlight CLI token found	Run setup, then store a token with `auth store --token-stdin`. Do not paste the token into chat or shell history.
401 Unauthorized	The token is missing, malformed, expired, or revoked. Ask a Searchlight admin for a fresh scoped token.
403 Forbidden	The token is valid but lacks the requested scope or site. Request explicit access or use a narrower command.
Unknown site	Run `mmai-searchlight annotations sites --json` and use a returned site slug.
Published npm version already exists	Bump `packages/searchlight-cli/package.json`, commit, push, then tag `searchlight-cli-v<version>`.

Publishing the CLI package

App deploys run from pushes to main. npm publishing is separate and tag-gated. The package publishes only when the tag matches the CLI package version.

Copy publish checklist commands

# Bump packages/searchlight-cli/package.json first.
npm test
npm run cli:pack:dry-run
git commit -m "Release Searchlight CLI <version>"
git push origin main
git tag searchlight-cli-v<version>
git push origin searchlight-cli-v<version>

Public surface and safety boundary

Public docs intentionally omit raw secrets, token values, active client lists, private analytics, internal-only runbooks, and credential locations. Treat all Searchlight data access as permissioned.