Metadata-Version: 2.4
Name: ivon-cli
Version: 0.2.2
Summary: ivon CLI — Meta Ads connector commands + MCP access for the ivon autonomous marketing team
Author: ivon (LemonTree Media)
License: Proprietary
Project-URL: Homepage, https://ivon.ai
Project-URL: Documentation, https://ivon.ai/profile
Keywords: ivon,meta,facebook,ads,mcp,cli
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: typer<1.0,>=0.12
Requires-Dist: httpx<1.0,>=0.27

# ivon CLI

Command-line access to the ivon Meta Ads connector — the same hosted MCP
server that powers ivon's agents, wrapped in human-friendly commands.

## Install

```bash
pip install ivon-cli         # from PyPI (or pipx install ivon-cli)
pip install -e cli/          # from the repo root, for development
```

## Login

```bash
ivon auth login              # opens browser → Google sign-in on ivon.ai → done
ivon auth status             # who am I + Facebook Ads connection state
ivon auth logout
```

Credentials are stored in `~/.ivon/credentials` (0600). The token is your
long-lived ivon API token — regenerate it on https://ivon.ai/profile to
revoke all CLI / MCP access.

## Meta Ads commands

```bash
ivon meta tools                                   # list every MCP tool, grouped
ivon meta tools get_insights                      # one tool: params, defaults + example
ivon meta tools get_insights --json               # same as JSON Schema (for agents)
ivon meta accounts                                # your ad accounts
ivon meta campaigns -a act_123 --status ACTIVE
ivon meta adsets -a act_123 -c <campaign_id>
ivon meta ads -a act_123
ivon meta insights act_123 -t last_7d --breakdown age
ivon meta call create_campaign -p account_id=act_123 -p name="Spring Sale" \
    -p objective=OUTCOME_TRAFFIC -p status=PAUSED
```

`ivon meta call <tool> -p key=value` reaches any tool on the server —
values parse as JSON when possible (`-p limit=25`, `-p targeting='{"geo_locations":{"countries":["US"]}}'`).

`ivon meta tools` reads a catalog snapshot bundled with the CLI, so discovery
is instant and works before login; `--refresh` re-fetches from the live
server. Refresh the bundled snapshot with `scripts/snapshot_cli_tools.py`
after changing the backend's tool surface.

## MCP client setup

```bash
ivon mcp config              # prints Claude Code / Claude Desktop config
ivon mcp config --show-token # same, with your real token embedded
```

## Environment overrides

- `IVON_API_URL` — point at a different backend (loopback allowed for dev;
  other hosts need `IVON_ALLOW_CUSTOM_API=1`).
- `IVON_CONFIG_DIR` — credentials directory (default `~/.ivon`).
