Metadata-Version: 2.4
Name: jiff-geo-cli
Version: 0.1.1
Summary: Command line tools for GEO platform automation.
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: typer<0.16.0,>=0.15.0
Requires-Dist: click<8.2.0,>=8.1.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: rich>=13.0.0
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: dev
Requires-Dist: build>=1.2.0; extra == "dev"
Requires-Dist: pytest>=8.0.0; extra == "dev"

# Geo CLI

Geo CLI is a command line tool for GEO platform automation. It is designed for agents and scripts: commands use explicit parameters and print JSON output so the result can be parsed reliably.

## Installation

Install from PyPI after the package is published:

```powershell
python -m pip install jiff-geo-cli
```

Check that the command is available:

```powershell
geo --version
geo --help
```

If `geo` is not found, run it through Python's script directory for the environment where you installed the package, or reinstall with the Python interpreter you actually use:

```powershell
python -m pip install --upgrade jiff-geo-cli
python -m pip show jiff-geo-cli
```

## Quick Start

Initialize the local configuration file:

```powershell
geo config init
```

Then edit the generated `.env` file and add your API keys. The default user config path on Windows is:

```text
C:\Users\<your-user>\.geo-cli\.env
```

You can also put a `.env` file in the current working directory. Values in the current directory override the user-level config.

## Configuration

Common configuration keys:

```text
GEO_API_KEY=your_geo_api_key

REPORT_AGENT_API_KEY=your_report_agent_api_key
REPORT_AGENT_ID=ec71a005-e170-4d32-8d4b-d6f144571875

ARTICLE_API_KEY=your_article_service_api_key
ARTICLE_GROUP_ID=your_article_group_id
ARTICLE_GROUP_TEXT=your_article_group_display_text
```

Defaults:

- `REPORT_AGENT_ID` can be omitted.

Required for article publishing:

- `ARTICLE_API_KEY`
- `ARTICLE_GROUP_ID`

Never paste API keys into chat logs or command output. Store them in `.env`.

## Command Groups

Geo CLI provides these command groups:

```text
geo config         Local configuration
geo brand          Brand management
geo service-type   Service type lookup
geo query-job      QueryJob management
geo query          Query management
geo eval-job       Evaluation job management
geo auto-job       Auto-monitor configuration
geo metrics        Metrics, data analysis, and reports
geo article        Article account management and publishing
```

Use `--help` at any level:

```powershell
geo metrics --help
geo article --help
geo article jobs --help
```

## Metrics and Reports

Use `geo metrics` to query metrics and request data analysis/report generation.

Generate or continue an analysis report:

```powershell
geo metrics analyze `
  --brand-id 123 `
  --message "Analyze this brand's recent performance and generate a concise report."
```

Continue an existing analysis session:

```powershell
geo metrics analyze `
  --brand-id 123 `
  --session-id "<session_id>" `
  --message "Continue the report and expand the URL citation section."
```

Query metric data:

```powershell
geo metrics my-brand-stats --brand-id 123 --start-date 2026-06-01 --end-date 2026-06-30
geo metrics my-prompt-stats --brand-id 123 --platform Qwen
geo metrics domain-stats --brand-id 123
geo metrics url-stats --brand-id 123
geo metrics qa-details --brand-id 123 --chat-date 2026-06-30 --platform Qwen
```

The report command can run for a long time. It is intended for data analysis and report generation tasks.

## Article Publishing

Use `geo article` for publishing platform account management, login sessions, and asynchronous article publishing jobs.

List supported platforms:

```powershell
geo article platforms
```

Create a login session:

```powershell
geo article login create --platform toutiao
```

Open the returned `live_url` and finish login in the browser. Then check the login session:

```powershell
geo article login get --session-id "<session_id>"
```

Bind the returned `channel_id` to an account:

```powershell
geo article accounts bind `
  --platform toutiao `
  --phone 13800138000 `
  --channel-id "<channel_id>"
```

List accounts:

```powershell
geo article accounts list --platform toutiao --with-runtime
```

Publish an article by account:

```powershell
geo article publish `
  --platform toutiao `
  --phone 13800138000 `
  --title "Article title" `
  --content-file .\article.md `
  --cover-image-url https://example.com/cover.jpg
```

Publishing is asynchronous. The command creates a publish job and returns immediately. It does not wait for completion.

Check a publish job:

```powershell
geo article jobs get --job-id "<job_id>"
```

If a job status is `waiting_cookie`, open the returned `live_url`, finish browser verification, then save the cookie and continue:

```powershell
geo article jobs save-cookie --job-id "<job_id>"
```

Cancel a publish job:

```powershell
geo article jobs cancel --job-id "<job_id>"
```

Common job statuses:

```text
queued                 Waiting in the server queue
checking_cookie        Checking login cookie
starting_remote_login  Starting remote login
waiting_cookie         Waiting for user login or verification
publishing             Publishing article
succeeded              Published successfully
failed                 Publish failed
cancelled              Cancelled
```

## Common Issues

### `geo` is not found

Install the package in the Python environment you are using:

```powershell
python -m pip install --upgrade jiff-geo-cli
python -m pip show jiff-geo-cli
```

On Windows, if you use conda, install with that environment's Python:

```powershell
D:\anaconda\envs\geo\python.exe -m pip install --upgrade jiff-geo-cli
D:\anaconda\envs\geo\Scripts\geo.exe --help
```

### Different environments show different versions

Each Python or conda environment has its own installed packages. Check the active package:

```powershell
python -m pip show jiff-geo-cli
where geo
Get-Command geo | Format-List Source,Path
```

Then upgrade the environment that owns the `geo` command.

### Missing API key or group ID

Run:

```powershell
geo config init
```

Then add the required key to `.env`. Article publishing requires both `ARTICLE_API_KEY` and `ARTICLE_GROUP_ID`.

## Development

Developer notes, local build steps, tests, and project structure are kept in `DEVELOPMENT.md`.
