Metadata-Version: 2.4
Name: agentai-cli
Version: 0.1.0
Summary: Command-line client for agent.ai — search, describe, and chat with AI agents from your terminal.
Project-URL: Homepage, https://agent.ai
Project-URL: Documentation, https://agent.ai/docs/cli
Project-URL: Repository, https://github.com/agent-ai/agentai-cli
Project-URL: Issues, https://github.com/agent-ai/agentai-cli/issues
Project-URL: Changelog, https://github.com/agent-ai/agentai-cli/releases
Author-email: "agent.ai" <support@agent.ai>
License: MIT
License-File: LICENSE
Keywords: agent.ai,agentai,agents,ai,cli,llm
Classifier: Development Status :: 4 - Beta
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 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: click<9.0,>=8.1
Requires-Dist: httpx<1.0,>=0.27
Requires-Dist: keyring<26,>=24
Requires-Dist: platformdirs<5,>=4
Requires-Dist: prompt-toolkit<4.0,>=3.0
Requires-Dist: pydantic<3.0,>=2.7
Requires-Dist: rich<15.0,>=13.7
Requires-Dist: tomli-w>=1.0
Requires-Dist: typer<1.0,>=0.12
Provides-Extra: binary
Requires-Dist: pyinstaller>=6.6; extra == 'binary'
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Provides-Extra: release
Requires-Dist: build>=1.2; extra == 'release'
Requires-Dist: twine>=5.0; extra == 'release'
Description-Content-Type: text/markdown

# `agentai` — agent.ai from your terminal

A polished, hand-crafted command-line client for [agent.ai]. Search
the marketplace, **chat with any agent**, run any of the **175+
public actions**, build new agents with the LLM-powered assistant,
manage your Composio integrations, and pipe everything into scripts —
all through the public REST API. Designed to feel like Claude Code or
Codex CLI in the terminal.

```text
$ agentai

▌ agent.ai
▌ command-line  v0.1.0

  user    Andrei Z   @andrei
  email   andrei@example.com
  tier    paid  (active)
  weekly  3 / 25 runs
  monthly 17 / 200 runs
  key     signed in  (keyring · 9f05…f0ab)
  base    https://api-lr.agent.ai/v1
  theme   modern
  health  ok

    agentai search 'sales prospecting'    find an agent
    agentai run fluximage                 run an agent (interactive)
    agentai mine                          list agents you've built
    agentai actions list                  browse the 175+ actions catalog
    agentai actions run invoke_llm        interactive prompt-fill + run
    agentai --help                        all commands and flags
```

## Documentation

- **[Features ↔ web mapping](docs/FEATURES.md)** — every agent.ai
  feature, with ✅ / ⚠️ / ❌ indicators for CLI vs website coverage.
- **[Command reference](docs/COMMANDS.md)** — every command, flag,
  exit code, env var, and file path with examples.
- **[Architecture](docs/ARCHITECTURE.md)** — module layout, import
  graph, and how to add a new endpoint or runner feature.
- **[Implementation plan](docs/PLAN.md)** — packaging + release flow.

## Install

```bash
pipx install agentai-cli       # recommended (isolated, on PATH)
uv tool install agentai-cli    # fastest
pip install --user agentai-cli # universal fallback
brew install agent-ai/tap/agentai      # macOS / Linuxbrew
curl -fsSL https://agent.ai/cli/install.sh | sh   # auto-detect
```

No Python? Grab a static binary for your platform from the
[GitHub releases][releases] and drop it on your `PATH`.

## Quickstart

```bash
agentai login                              # browser → paste key → keyring
agentai status                             # name + tier + usage dashboard

# Discover
agentai search "image generation"
agentai mine

# Run agents
agentai run fluximage                      # interactive REPL (default)
agentai run fluximage -i image_prompt='cat' --json

# Run any of the 175+ catalog actions
agentai actions run invoke_llm \
  -i instructions='Say hello in one word' \
  -i llm_engine=claude-opus-4-7 --skip-optional

# OmniAgent chat — multi-LLM, conversation-aware
agentai chat
agentai chat --model claude-opus-4-7
agentai chat --with-agent fluximage --with-composio

# Build agents from a description
agentai builder new "Summarize the top story on Hacker News every morning"

# Manage Composio integrations
agentai composio list
agentai composio enable github

# Inspect your run history
agentai runs --since 2026-04-01
```

The full command index is in [COMMANDS.md](docs/COMMANDS.md).

## What's in the box

| Surface | Command | Notes |
|---|---|---|
| Auth + identity dashboard | `login`, `logout`, `status` | OS keyring, name/email/tier/usage in one round-trip |
| Discover agents | `search`, `mine`, `describe` | Algolia-ranked + client-side runs/rating sort + did-you-mean |
| Run agents | `run` (interactive default + scripted one-shot), `chat` (alias) | Auto-detected from `--json` / `--stdin` / `--from-file` / non-TTY |
| Run history | `runs` | Pagination + agent / date filters + relative timestamps |
| Action catalog | `actions list/search/describe/run/tags/update` | All 175+ catalog actions, schema-driven prompts |
| Builder | `builder new/edit` | LLM-powered authoring with `/save`, `/run`, `/diff` |
| OmniAgent chat | `chat` (no agent) | Multi-LLM, `--with-agent`, `--with-composio` |
| Composio | `composio list/enable/disable/connect/tools/execute` | Same toggle store as the web UI |
| Settings | `config get/set/path` | XDG-style config + theme switching |

For the **full feature ↔ website matrix**, see
[docs/FEATURES.md](docs/FEATURES.md).

## What it can't do (today)

The CLI is API-key-authenticated end-to-end, but a few features
remain web-only by design or by surface area:

- **Visual workflow canvas** — drag-drop builder UX is web-only.
- **Project rooms / saved-conversation persistence / KB attachments**
  for the OmniAgent — server-side state is web-only today; `/projects`
  inside the CLI prints honest "coming soon" placeholders.
- **OAuth flows for connecting Composio integrations** — `agentai
  composio connect` deep-links to <https://agent.ai/user/integrations>;
  finish in the browser, then `agentai composio list`.
- **Streaming token-by-token output** — `invoke_llm` and
  `invoke_agent` are sync today; spinner with elapsed time + rotating
  verbs while in flight. Will switch to streaming when the API
  exposes it.
- **API key generation / rotation, billing, team management** — live
  in the web settings.

Full breakdown in [docs/FEATURES.md](docs/FEATURES.md).

## Polish

The CLI is built to feel like a hand-crafted tool, not a script:

- **Welcome screen** when you run `agentai` with no args.
- **Status dashboard** showing identity, tier, usage, key source, and
  API health in one glance.
- **Rotating thinking phrases** (Drafting…, Reviewing…, Composing…)
  with elapsed-time footer, like Claude Code's `✻ X.Ys`.
- **Bottom toolbar** in chat with the active agent and key bindings.
- **History-based autosuggest** so up-arrow + tab work like fish.
- **Did-you-mean** suggestions when an agent or action name doesn't
  resolve.
- **Schema-driven prompts** for actions: enums become numbered
  choices, booleans become y/n, integers/numbers honour
  `minimum`/`maximum`.
- **Three themes** (`modern`, `minimal`, `ascii`).
- **Smart response rendering.** Image-only HTML (`<img src="…" />` —
  the shape returned by `fluximage`, `imagegen`, `gpt-image-generation`,
  etc.) is unwrapped into a clean `file / url / open` card with a
  copy-pasteable `curl -O` command. Full HTML reports get tag-stripped
  to readable text. Markdown stays Markdown. Empty responses show a
  calm `(no output)` instead of a blank panel.
- **CLI hint in chat.** Every chat session prints the equivalent
  non-interactive form so you never have to re-discover the flags.
- **Runner-page URL after every run.** Each agent response shows
  `view on web → https://agent.ai/agent/<slug>?rid=<run_id>` so a
  cmd-click takes you straight to the same execution on the web. Run
  ids in `agentai runs` are OSC-8 hyperlinks. `agentai open <slug>`
  and `agentai open <run_id> --agent <slug>` open the right URL
  directly.
- **Descriptive prompts.** Interactive input collection leads with the
  human-readable question — the OpenAPI `description` for actions, or
  a humanized form of the variable name for agents (`image_prompt` →
  "Image prompt", `linkedin_url` → "LinkedIn URL").

## Configuration

```bash
agentai config get                        # dump everything
agentai config set base_url https://...   # point at staging
agentai config set default_status all     # search private + team by default
agentai config set theme ascii            # for older terminals
agentai config path                       # show where it lives
```

Environment variables override the file:

| Variable                    | Effect                                                |
| --------------------------- | ----------------------------------------------------- |
| `AGENTAI_API_KEY`           | Use this key for the session.                         |
| `AGENTAI_BASE_URL`          | Talk to a different public-API host.                  |
| `AGENTAI_INTERNAL_BASE_URL` | Talk to a different `/api/v2/*` host.                 |
| `AGENTAI_THEME`             | `modern` (default), `minimal`, or `ascii`.            |
| `NO_COLOR`                  | Disable ANSI colours (also `--no-color`).             |

## Development

This package lives at `packages/agentai-cli/` in the
[agent.ai monorepo][repo]. To hack on it:

```bash
cd packages/agentai-cli
python3 -m venv .venv      # Python 3.11+ required
source .venv/bin/activate
pip install -e ".[dev]"
pytest                     # 260+ tests
ruff check src tests
```

Architecture & distribution rationale: see
[docs/PLAN.md](docs/PLAN.md). What ships in each command vs. the web
UI: see [docs/FEATURES.md](docs/FEATURES.md). Per-command details +
exit codes + env vars + file locations: see
[docs/COMMANDS.md](docs/COMMANDS.md).

## Releasing

The package supports **Python 3.11+** and ships to PyPI as
[`agentai-cli`](https://pypi.org/project/agentai-cli/). Routine
releases run end-to-end through GitHub Actions via
[OIDC trusted publishing](https://docs.pypi.org/trusted-publishers/) —
no API tokens stored in the repo.

### One-command release (recommended)

```bash
cd packages/agentai-cli

# Rehearse — bumps in-memory, builds, smoke-tests, no commits.
scripts/release.sh patch --dry-run

# Real release: bump → build → tag → push. CI handles publish.
scripts/release.sh patch       # 0.1.0 → 0.1.1
scripts/release.sh minor       # 0.1.0 → 0.2.0
scripts/release.sh 1.0.0rc1    # explicit version
```

After `scripts/release.sh` pushes the `agentai-cli-vX.Y.Z` tag, the
`Release` workflow:

1. Builds the sdist + wheel and verifies the tag matches
   `[project].version` in `pyproject.toml`.
2. Smoke-installs the wheel into a clean venv and runs
   `agentai --version` / `--help`.
3. Publishes to PyPI through OIDC.
4. Builds static binaries for macOS (arm64 + x86_64), Linux x86_64,
   and Windows x86_64 with PyInstaller, attaches them to the GitHub
   Release.
5. Bumps the Homebrew tap formula via `brew bump-formula-pr`.

### Manual / offline release

When CI isn't an option (offline release, fast hotfix from a laptop):

```bash
scripts/build.sh                       # lint + tests + build + smoke
scripts/publish.sh --test              # upload to test.pypi.org
scripts/publish.sh                     # upload to pypi.org (prompts)

# Or in one shot:
scripts/release.sh patch --publish=test
scripts/release.sh patch --publish=prod
```

Manual uploads need a PyPI API token in `~/.pypirc` or the
`TWINE_USERNAME=__token__` + `TWINE_PASSWORD=pypi-...` env vars.

### Workflow dispatch (Test PyPI dry-run)

Want to verify the artifacts on Test PyPI without tagging? Trigger
the release workflow manually:

1. Repo → Actions → **Release** → **Run workflow**.
2. Leave `test_pypi: true`.
3. The workflow builds + uploads to <https://test.pypi.org/>.

### Version bumps without a release

```bash
scripts/bump_version.py --print     # show current
scripts/bump_version.py patch       # bump pyproject.toml only
scripts/bump_version.py 0.5.0       # set explicit
```

This is orthogonal to the release flow — handy for opening a draft PR
where you want the bump in the diff but aren't ready to ship.

### Setting up trusted publishing (one-time)

For maintainers wiring this up the first time:

1. Create the project on [PyPI](https://pypi.org/manage/projects/) and
   [Test PyPI](https://test.pypi.org/manage/projects/).
2. Under each project: *Settings → Publishing → Add a new publisher*.
3. Owner: `agent-ai` · repo: `agentai-cli` · workflow:
   `release.yml` · environment: `pypi` (production) and `testpypi`
   (Test PyPI).
4. Add matching environments in the GitHub repo settings — no secrets
   needed; OIDC handles auth.

## License

MIT. See [LICENSE](LICENSE).

[agent.ai]: https://agent.ai
[releases]: https://github.com/agent-ai/agentai-cli/releases
[repo]: https://github.com/HubSpotLabs/simple_ai
