Metadata-Version: 2.4
Name: zog-cli
Version: 0.3.0
Summary: Zoho Mail CLI modeled after gog.
Author: Alethi founders
License: MIT
Project-URL: Homepage, https://github.com/Alethi-Consulting/zog
Project-URL: Repository, https://github.com/Alethi-Consulting/zog
Project-URL: Issues, https://github.com/Alethi-Consulting/zog/issues
Keywords: cli,zoho,mail,oauth
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Communications :: Email
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31
Requires-Dist: platformdirs>=4
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-mock>=3.14; extra == "dev"
Dynamic: license-file

# zog

[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)

`zog` is a Python CLI for Zoho Mail, designed to feel familiar to anyone who already uses `gog` for Google services. It keeps the dependency set small, uses `argparse`, stores credentials under `~/.config/zogcli/`, and supports both machine-readable and terminal-friendly output.

## Install

```bash
pipx install zog-cli
```

```bash
uv tool install zog-cli
```

For local development:

```bash
uv venv
source .venv/bin/activate
uv pip install -e .[dev]
```

## Quickstart

```bash
pipx install zog-cli
zog auth add me@example.com
```

This opens your browser to authorize zog. After you click Allow, the CLI captures the authorization callback automatically and stores your tokens locally.

For headless servers or SSH sessions without port forwarding, use the out-of-band flow:

```bash
zog auth add me@example.com --no-browser
```

For power users who want to use their own Zoho app, use `--self-client`.

## Usage

Authorize your mailbox:

```bash
zog auth add you@yourdomain.com
```

Search mail:

```bash
zog mail search -a you@yourdomain.com "from:cloudflare" --max 3
```

List folders:

```bash
zog mail folders -a you@yourdomain.com
```

Dry-run a send:

```bash
zog mail send \
  -a you@yourdomain.com \
  --to friend@example.com \
  --subject "zog test" \
  --body "hello from zog" \
  --dry-run
```

### Importing existing Zoho credentials

If you already have a JSON file with `client_id`, `client_secret`, and `refresh_token` from a previous Zoho Self Client setup, you can import it directly:

```bash
zog auth import-legacy /path/to/credentials.json
```

## Command Reference

```text
zog auth add <email> [--services mail] [--no-browser] [--port N]
zog auth list
zog auth remove <email>
zog auth import-legacy <path>

zog mail search -a <email> "<query>" [--max N] [-j|-p]
zog mail get -a <email> <messageId> [-j|-p]
zog mail thread get -a <email> <threadId> [-j|-p]
zog mail send -a <email> --to ... --subject ... --body ...
zog mail folders -a <email> [-j|-p]

zog --version
```

Global flags follow gog-style conventions:

- `-a, --account`
- `-j, --json`
- `-p, --plain`
- `-n, --dry-run`
- `-v, --verbose`
- `-h, --help`

## Output Modes

- Default: aligned table output for list-style commands.
- `--json`: `{"status": "...", "data": ...}` envelope.
- `--plain`: stable TSV for scripting.

## OAuth Setup

By default `zog auth add` uses Zoho's OAuth 2.0 Authorization Code flow with a local loopback server, so no manual Self Client setup is required. If you prefer to use your own Zoho app, use the `--self-client` flag:

```bash
zog auth add you@yourdomain.com --self-client
```

Then create or select a Self Client in the Zoho API Console:

<https://api-console.zoho.com/>

Use these scopes:

```text
ZohoMail.messages.ALL,ZohoMail.accounts.READ,ZohoMail.folders.READ
```

## Contributing

1. Create a virtual environment with `uv venv`.
2. Install the package in editable mode with `uv pip install -e .[dev]`.
3. Run `pytest -q`.
4. Keep changes small, typed, and focused.

See [LICENSE](LICENSE) for license terms.
