worai 1.1.0

Add your description here

worai

Command-line toolkit for WordLift operations and SEO checks. Pronunciation: "waw-RYE"

Docs: https://docs.wordlift.io/worai/

Install

• pipx install worai
• pip install worai

Full docs: https://docs.wordlift.io/worai/

If you plan to run seocheck, install Playwright browsers:

• playwright install chromium

Quick Start

• worai --help
• worai seocheck https://example.com/sitemap.xml
• worai google-search-console --site sc-domain:example.com --client-secrets ./client_secrets.json
• worai <command> --help

Configuration

Config file (TOML) discovery order:

• --config
• WORAI_CONFIG
• ./worai.toml
• ~/.config/worai/config.toml
• ~/.worai.toml

Profiles:

• [profile.<name>] with --profile or WORAI_PROFILE

Common keys:

• wordlift.api_key
• gsc.client_secrets
• gsc.token

Supported environment variables:

• WORAI_CONFIG — path to a config TOML file (overrides discovery order).
• WORAI_PROFILE — profile name under [profile.<name>].
• WORAI_LOG_LEVEL — default log level (debug|info|warning|error).
• WORAI_LOG_FORMAT — default log format (text|json).
• WORDLIFT_KEY — WordLift API key for entity operations.
• WORDLIFT_API_KEY — alternate WordLift API key name (also accepted by some commands).
• GSC_CLIENT_SECRETS — path to OAuth client secrets JSON for GSC.
• GSC_TOKEN — path to store the OAuth token.
• GSC_OUTPUT — default output CSV path for GSC export.

Example environment setup:

export WORDLIFT_KEY="wl_..."
export WORAI_CONFIG="~/worai.toml"
export WORAI_PROFILE="dev"
export GSC_CLIENT_SECRETS="~/client_secrets.json"

Example worai.toml:

[defaults]
log_level = "info"

[wordlift]
api_key = "wl_..."

[gsc]
client_secrets = "/path/to/client_secrets.json"
token = "/path/to/gsc_token.json"

Commands

Full docs: https://docs.wordlift.io/worai/

• seocheck — run SEO checks against sitemap URLs.
• google-search-console — export GSC page metrics to CSV.
• dedupe — deduplicate WordLift entities by schema:url.
• canonicalize-duplicate-pages — choose canonical URLs using GSC KPIs.
• delete-entities-from-csv — delete entities listed in a CSV.
• find-faq-page-wrong-type — find/patch FAQPage type issues.
• find-missing-names — list pages missing schema:name/headline.
• find-url-by-type — extract schema:url by type from RDF.
• link-groups — build/apply LinkGroup data from CSV.
• patch — patch entities from RDF.
• upload-entities-from-turtle — upload .ttl files with resume.

Command help:

• worai <command> --help

Autocompletion:

• worai --install-completion
• worai --show-completion

Examples

seocheck

• worai seocheck https://example.com/sitemap.xml
• worai seocheck https://example.com/sitemap.xml --output-dir ./seocheck-report --save-html

google-search-console

• worai google-search-console --site sc-domain:example.com --client-secrets ./client_secrets.json

canonicalize-duplicate-pages

• worai canonicalize-duplicate-pages --input gsc_pages.csv --output canonical_targets.csv --kpi-window 28d --kpi-metric clicks

dedupe

• worai dedupe --dry-run

find-faq-page-wrong-type

• worai find-faq-page-wrong-type ./data.ttl --dry-run --replace-type
• worai find-faq-page-wrong-type ./data.ttl --patch --replace-type

find-missing-names

• worai find-missing-names ./data.ttl

find-url-by-type

• worai find-url-by-type ./data.ttl schema:Service schema:Product

link-groups

• worai link-groups ./links.csv --format turtle
• worai link-groups ./links.csv --apply --dry-run --concurrency 4

patch

• worai patch ./data.ttl --dry-run --add-types

upload-entities-from-turtle

• worai upload-entities-from-turtle ./entities --recursive --limit 50

Troubleshooting

• Playwright missing browsers:
  • playwright install chromium
• OAuth token issues:
  • Remove the token file and re-run worai google-search-console.