G1GEO CLI

Official command-line client for the G1GEO Automation API.

Requirements

• Node.js 22 or 24
• A G1GEO account for browser login, or a scoped Service Token for unattended use

Install

npm install -g @g1geo/cli@latest
g1geo --version

AI agents should read the business workflow and operating guide bundled with the installed CLI before using it, and read it again after every upgrade:

g1geo guide

g1geo guide reads its Markdown document locally and requires no authentication. Before printing it, the CLI performs a best-effort check of the public npm latest dist-tag. If the installed version is behind, an upgrade recommendation is written to stderr while the Guide remains unchanged on stdout. Successful checks are cached for 24 hours, and registry failures never prevent the Guide from loading. Prerelease dist-tags are not considered by the public update workflow.

For a normal user or an interactive Agent session, log in through the browser:

g1geo auth login
g1geo auth status
g1geo status

On a remote or headless host, the CLI prints a URL and short code:

g1geo auth login --no-browser

The OAuth access token is refreshed automatically. Credentials are stored in macOS Keychain, Windows Credential Manager, or Linux Secret Service. If a headless Linux environment has no system credential service, the CLI falls back to a private mode-0600 credential file and prints its path.

The CLI keeps one browser session per API endpoint. To change the signed-in human identity, run g1geo auth logout and log in again. Concurrent unattended identities should use separate least-privilege Service Tokens.

Browser approval is account-level: it grants the standard CLI permission bundle for every product currently or subsequently visible to the signed-in identity. Agents can create and update products, but cannot delete an entire product.

For CI and permanently unattended Agents, create a least-privilege Service Token in the G1GEO SaaS settings page and inject it through the secret manager:

export G1GEO_TOKEN='g1geo_pat_...'
g1geo auth status

G1GEO_TOKEN takes precedence over a stored browser session. Tokens are never accepted as command-line arguments.

Commands

g1geo doctor
g1geo capabilities
g1geo status
g1geo status --since 24h --limit 5
g1geo --product prd_xxx status
g1geo products list
g1geo products create --name "Brand"
g1geo products update prd_xxx --name "New name"

g1geo --product prd_xxx knowledge get
g1geo --product prd_xxx knowledge documents add --file reference.pdf
g1geo --product prd_xxx knowledge documents add --input reference.json
g1geo --product prd_xxx materials images upload --file case.png --category gcat_xxx
g1geo --product prd_xxx materials content list
g1geo --product prd_xxx instructions config update --input writing-config.json

g1geo --product prd_xxx questions generate --title "GEO consulting questions" --keywords "GEO consulting" --brand-name "Brand" --wait
g1geo --product prd_xxx questions detections qset_xxx
g1geo --product prd_xxx articles generate --topic "How should a company start GEO optimization?" --wait
g1geo --product prd_xxx articles generate --question-set qset_xxx
g1geo --product prd_xxx articles generate --group agrp_xxx
g1geo --product prd_xxx articles groups create --name "GEO fundamentals" --question "What is GEO?"
g1geo --product prd_xxx articles tasks list
g1geo --product prd_xxx assistant markers detect art_xxx
g1geo --product prd_xxx article-fission generate --article art_xxx --count 5 --wait
g1geo --product prd_xxx article-fission generate --url https://example.com/article
g1geo --product prd_xxx article-fission generate --file source.md --reference-materials

g1geo --product prd_xxx geo platforms
g1geo --product prd_xxx geo detect --question-set qset_xxx
g1geo --product prd_xxx geo detect --question "Which brand is recommended?" --channel app
g1geo --product prd_xxx geo result grun_xxx
g1geo --product prd_xxx geo retry grun_xxx
g1geo --product prd_xxx geo runs export grun_xxx --format json --out report.json
g1geo --product prd_xxx geo brand-reports create --wait
g1geo --product prd_xxx geo brand-reports export brep_xxx --out brand-report.pdf
g1geo --product prd_xxx geo analysis summary
g1geo --product prd_xxx tracking trends trk_xxx

# Versioned customer delivery reports (import creates a draft only)
g1geo delivery-reports validate --input report-bundle.json
g1geo --product prd_xxx delivery-reports import --input report-bundle.json
g1geo --product prd_xxx delivery-reports preview --profile customer-weekly-v1 --revision drr_xxx
g1geo --product prd_xxx delivery-reports publish --profile customer-weekly-v1 --revision drr_xxx --yes
g1geo --product prd_xxx delivery-reports rollback --profile customer-weekly-v1 --revision drr_xxx --yes

g1geo publishing teams list
g1geo publishing devices list --online
g1geo --team team_xxx publishing accounts list
g1geo --team team_xxx --device dev_xxx publishing accounts check-login pacc_xxx --wait
g1geo --product prd_xxx --team team_xxx --device dev_xxx publishing publish --article art_xxx --account pacc_xxx --yes --wait
g1geo publishing media list --high-inclusion --page-size 20
g1geo --product prd_xxx publishing publish --article art_xxx --media gmed_xxx --yes --wait
g1geo jobs get job_xxx
g1geo publishing retry job_xxx --yes --wait
g1geo publishing audit list

g1geo status is the compact continuity surface for Agents and project managers. It orders visible products (the current GEO project container) by recent product, official-CLI mutation, or Job activity, then returns recent actions, resumable Jobs, latest GEO/publishing context, and review signals. --since changes the recent-action window; it does not hide active work. The activity list covers official CLI mutations rather than all Web activity. A stale G1GEO_PRODUCT_ID cannot narrow discovery; use an explicit --product when that is intended.

Delivery reports use immutable, product-scoped revisions. validate, diff, preview, and import never change the customer-visible revision; an explicit publish --yes or rollback --yes atomically switches the current pointer. After the first capability deployment, weekly report updates do not require a Web build, service restart, or Nginx deployment. See the bundled g1geo-weekly-report Skill for source-sheet classification, full-history merging, metric null semantics, and evidence-backed recommendations.

Complex content mutations use --input <path> with a UTF-8 JSON object; --input - reads the object from stdin. Publishing deliberately uses repeatable --article/--material flags with exactly one target kind: desktop --account or GEO-media --media. Product context remains explicit for product business commands; team and device are additionally required only for desktop accounts. g1geo guide routes real business intent into complete workflows and shared execution rules; command-specific syntax remains available through --help.

g1geo publishing devices list adds a structured desktop_connection result. setup_required includes https://g1geo.com/publisher plus installation and media-account login steps; offline means a registered client exists but is not currently online; online reports the registered and online device counts. Check this state instead of treating every filtered items: [] result as “not installed.”

0.3.2 covers the /app workspace scope plus direct publishing: company knowledge, reference documents, image materials, writing requirements, generated question-set maintenance and recent detection summaries, article generation and editing, article inspection and rewrites, one-step text-only article fission, GEO detection, analysis dashboards, effect tracking, unified asynchronous Jobs, desktop devices and publisher accounts, and restricted GEO-media distribution.

GEO-media discovery is fixed to active media_type = 3 records. The only business filter is --high-inclusion; pagination keeps the roughly two hundred live results bounded. Each item returns only its gmed_... ID, name, platform, selection remark, credit cost, RMB amount, and high-inclusion flag. The remark gives an Agent useful suitability context but is not a guaranteed publishing outcome. Customer pricing is 10 credits = RMB 1, so a 200-credit placement costs RMB 20 per content item. Keyword, category, platform, price, inclusion-type, AI-platform, and sort filters are intentionally unavailable.

Core asynchronous generation and publishing commands accept --wait. Shared controls are --interval, --wait-timeout, --allow-partial, and --cancel-on-interrupt; the same controls are available through g1geo jobs wait <job-id>. GEO detection is intentionally different: geo detect and geo retry return immediately, while repeated geo result calls provide bounded question-platform progress and the final conclusion without holding one Agent tool call open for up to thirty minutes.

Publishing and login checks expose only unified job_... IDs. Desktop command IDs, provider media IDs, and publishing batch/item/record IDs remain internal. Desktop publishing supports cancel and failed-target retry. GEO-media jobs represent upstream submission, cannot be scheduled/cancelled/retried, and require a new explicit --yes publish if another attempt is needed.

Question generation is one step: a successful Job saves the question set automatically. The final Job result includes result.question_set_id plus the complete saved resource in result.question_set; --title is optional and defaults to the supplied keywords. There is no separate questions commit command.

Normal article generation uses one articles generate command with exactly one of --topic, --question-set, or --group. Question sets synchronize into their corresponding article groups; each invocation creates an internal generation run so the Job result contains only that run's selected tasks and effective writing/reference snapshot, not the group's historical articles.

Article fission no longer exposes its internal seed model through the Job result. With article-fission generate --wait, data.job.result contains requested/generated/failed/cancelled counts and per-variant article status, public art_... ID, title, or error.

GEO detection uses three high-level intents. geo detect takes a question set or repeated direct questions, defaults the brand and competitors from Knowledge, defaults --channel to web, and chooses the configured recommended platforms when none are supplied. geo result accepts grun_... or job_... and reports progress by question × platform, including a separate reporting phase. geo retry automatically retries only failed/cancelled cells and returns a child Job without task/platform JSON; eligible worker-backed runs are required, so historical legacy runs return retry_unavailable rather than starting a long synchronous retry.

It deliberately excludes product detection until that workflow is complete enough for formal Agent use. Generic content checking, template/LLM GEO question suggestion helpers, and low-level article deletion, direct regeneration, version restoration, article-card theme discovery, and image-text conversion/history are also kept out of the Agent command surface. It additionally excludes the obsolete automatic content-production flow, the not-yet-released hotspot flow, and the redundant Web publishing route. Account publishing uses the desktop WebSocket command queue; GEO-media publishing uses the existing server-side third-party publisher and exposes only type-3 media. The CLI never receives browser Cookie, plaintext platform credentials, provider media IDs, or upstream pricing.

The default API endpoint is:

https://api.g1geo.com/automation/v1

Use G1GEO_BASE_URL for a test deployment. Product context must be explicit. Publishing-team and desktop-device context are additionally required for desktop-account publishing, but not for GEO-media publishing.

For example:

G1GEO_BASE_URL='https://test.g1geo.com/automation/v1' \
  g1geo auth login --no-browser

Agent output

Agents do not need to choose an output format. guide and auth login default to human-readable guidance; deterministic result commands default to one stable JSON envelope on stdout. Diagnostics go to stderr, and failures use stable non-zero exit codes.

--output human|json|jsonl, --json, and G1GEO_OUTPUT remain available as explicit operator overrides.

Security

• Do not commit G1GEO_TOKEN.
• Use a CI secret manager for unattended execution.
• Service Tokens should use the minimum scopes and product access required.
• Browser sessions use one-hour opaque access tokens and rotating refresh tokens.
• Browser sessions receive the standard account-level CLI permission bundle; whole-product deletion is not available through the CLI or Automation API.
• g1geo auth logout revokes the complete server-side token family; --local is an explicit offline-only escape hatch.
• Local configuration never contains credentials. The headless fallback credential file is separate and mode 0600 on Unix-like systems.