Skip to content

Add AGENTS.md for Cursor Cloud development environment #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
TravisDart wants to merge 1 commit into
base: master
Choose a base branch
from
Draft

Add AGENTS.md for Cursor Cloud development environment #1

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 54 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
# AGENTS.md

## Project overview

**pull-index** is a Python CLI for reading Elasticsearch snapshot repository metadata from S3 and optionally exporting documents via ephemeral Docker Elasticsearch. See `README.md` for command usage.

## Cursor Cloud specific instructions

### Running the CLI

All commands run from the repo root with `uv`:

```bash
uv run main.py list s3://<bucket>/<prefix>/
uv run main.py download s3://<bucket>/<prefix>/ '<index-name>'
uv run main.py export-documents s3://<bucket>/<prefix>/ '<index-name>'
```

There is no long-running dev server. The CLI is the application.

### Dependencies

| Tool | Purpose |
|------|---------|
| **uv** + **Python 3.13** | Runtime (managed via `pyproject.toml` / `.python-version`) |
| **AWS CLI v2** | S3 access for all commands |
| **Docker** | Required only for `export-documents` |

### AWS credentials

S3 commands need valid AWS credentials (`AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY`, or `~/.aws/credentials`). Without them, `list` and `download` fail when reading from S3 (even if `.pull-index/generation-files.json` cache exists).

### Docker in Cloud Agent VMs

The Docker daemon uses the `fuse-overlayfs` storage driver in this environment. If `docker info` reports permission errors, ensure `dockerd` is running and `/var/run/docker.sock` is accessible (e.g. `sudo chmod 666 /var/run/docker.sock` or membership in the `docker` group).

`export-documents` pulls `docker.elastic.co/elasticsearch/elasticsearch:<version>` on first use.

### Repository listing cache

After the first successful `list` or `download` for a repository URI, index generation file paths are cached in `.pull-index/generation-files.json`. Subsequent commands skip the slow S3 listing. Delete `.pull-index/` to force a refresh.

### Lint / tests

There is no configured linter or automated test suite in this repo. For a quick sanity check:

```bash
uv run python -m py_compile main.py snapshot_export.py repo_es_version.py
uv run main.py --help
```

### Example repository

The README documents `s3://cold-qa01/2022-Q1/` as an example snapshot path.