Metadata-Version: 2.4
Name: tteg
Version: 0.4.2
Summary: Free stock image search CLI for agents.
Author: Kushal
License: MIT
Project-URL: Homepage, https://tteg.kushalsm.com
Keywords: unsplash,stock-images,cli,ai-agents,image-search
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Multimedia :: Graphics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: click>=8.1.7
Requires-Dist: mcp[cli]<2,>=1
Requires-Dist: requests>=2.32.0

# tteg

Free stock image search CLI and MCP server for AI coding agents. No API keys, no setup.

```bash
uv tool install tteg && tteg "mountain sunset"
```

Returns image URLs from Unsplash — ready to drop into any LLM workflow.

## Install

```bash
uv tool install tteg
# or: pip install tteg
```

## Usage

```bash
tteg "mountain sunset"
tteg "hero banner" -n 8 --orientation landscape
tteg "office workspace" --width 1920 --height 1080
tteg save "saas team working" ./public/hero
tteg batch examples/landing-page-images.json
```

## Output

```json
{
  "query": "mountain sunset",
  "results": [
    {
      "id": 1,
      "title": "A colorful sunrise over Jamnik village",
      "image_url": "https://images.unsplash.com/photo-...",
      "thumb_url": "https://images.unsplash.com/photo-...&w=200"
    },
    {
      "id": 2,
      "title": "Brown mountains under orange sky",
      "image_url": "https://images.unsplash.com/photo-...",
      "thumb_url": "https://images.unsplash.com/photo-...&w=200"
    }
  ]
}
```

## Options

| Flag | Default | Description |
|------|---------|-------------|
| `-n`, `--count` | 5 | Number of results (1–10) |
| `--orientation` | any | `landscape`, `portrait`, `square`, or `any` |
| `--width` | — | Target width in pixels |
| `--height` | — | Target height in pixels |

## Save Locally

```bash
tteg save "saas team working" ./public/hero
tteg save "workspace desk" ./public/images/hero.jpg --orientation landscape
```

`tteg save` searches, picks one result, downloads it locally, and prints JSON with the saved path.

## Batch A Page

```bash
tteg batch examples/landing-page-images.json
```

Manifest format:

```json
{
  "images": [
    {
      "query": "saas dashboard hero",
      "output": "./public/images/hero",
      "orientation": "landscape"
    },
    {
      "query": "startup team meeting in office",
      "output": "./public/images/team",
      "orientation": "landscape"
    }
  ]
}
```

Use this when the page needs a hero, team shot, founder photo, testimonial portrait, or menu shot in one pass.

## Starter Kit Drop-In

If you maintain a Claude Code, Codex, or Cursor starter kit, use the copy-paste blocks in [STARTER_KIT.md](STARTER_KIT.md).

It includes:

- a `CLAUDE.md` snippet for real-photo frontend work
- an `AGENTS.md` snippet for Codex projects
- an MCP config block for tool access inside agent hosts

## Why

Agents frequently need real images — hero banners, product shots, blog headers. The normal path (register for Unsplash, get an API key, handle rate limits) is too much friction for a mid-task agent call.

`tteg` abstracts all of that. One install, one command, clean JSON out.

## MCP server

Use tteg directly from Claude Code, Cursor, or any MCP-compatible host from this repo:

```json
{
  "mcpServers": {
    "tteg": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/kiluazen/tteg", "tteg-mcp"]
    }
  }
}
```

You can also install the package once and run `tteg-mcp` locally.

Exposes:

- `search_images(query, count, orientation, width, height)`
- `save_image(url, output_path)`
- `search_and_save_image(query, output_path, index, orientation, width, height)`
- `batch_save_images(images)`

No API key needed.

## Links

- [tteg.kushalsm.com](https://tteg.kushalsm.com) — landing page
- [PyPI](https://pypi.org/project/tteg/) — `pip install tteg`
- Free: 50 queries/day. No account needed.
