npm package: @ipe-city/agents
Description: One-command CLI for AI agents to submit apps and people into Ipe Hub.
Latest version: 0.1.0

# @ipe-city/agents

One-command CLI for AI agents to submit apps and people into Ipe Hub.

## Quick start

Submit an app in a single command — no install, no env vars, no files:

```bash
npx @ipe-city/agents submit-app \
  --api-url https://hub.ipe.city \
  --json '{"name":"Village Grants Radar","websiteUrl":"https://radar.ipe.city","iconUrl":"https://cdn.ipe.city/radar-icon.png","previewImageUrl":"https://cdn.ipe.city/radar-preview.png","description":"Tracks live funding opportunities for builders.","category":"earn"}'
```

Submit a person:

```bash
npx @ipe-city/agents submit-person \
  --api-url https://hub.ipe.city \
  --json '{"name":"Ana Builder","avatarUrl":"https://cdn.ipe.city/ana.jpg","bio":"Design systems and governance tooling.","xProfileUrl":"https://x.com/anabuilder"}'
```

Submissions enter a moderation queue. Trusted agents (configured server-side) are auto-approved.

## Payload reference

### App (required fields)

| Field | Type | Description |
|-------|------|-------------|
| `name` | string | App name |
| `websiteUrl` | string | Valid HTTP(S) URL |
| `iconUrl` | string | Valid HTTP(S) URL to app icon |
| `previewImageUrl` | string | Valid HTTP(S) URL to preview image |
| `description` | string | What the app does |
| `category` | string? | One of: connect, earn, coordinate, safety, city-ops, governance, food-nature, infrastructure, community-life |

### Person (required fields)

| Field | Type | Description |
|-------|------|-------------|
| `name` | string | Display name |
| `avatarUrl` | string | Valid HTTP(S) URL to avatar |
| `bio` | string | Short biography |
| `xProfileUrl` | string? | X/Twitter profile URL |
| `linkedInUrl` | string? | LinkedIn profile URL |
| `websiteUrl` | string? | Personal website URL |

## Input methods

The CLI accepts payloads three ways (in priority order):

```bash
# 1. Inline JSON (preferred for agents)
npx @ipe-city/agents submit-app --json '{"name":"..."}' --api-url <url>

# 2. From a file
npx @ipe-city/agents submit-app --file ./payload.json --api-url <url>

# 3. Piped via stdin
echo '{"name":"..."}' | npx @ipe-city/agents submit-app --api-url <url>
```

## Flags vs environment variables

Every connection parameter can be passed as a flag (preferred for one-off commands) or set as an environment variable (for persistent shells):

| Flag | Environment variable | Purpose |
|------|---------------------|---------|
| `--api-url` | `IPE_AGENT_API_BASE_URL` | API base URL |
| `--token` | `IPE_AGENT_SUBMIT_TOKEN` | Bearer token for submissions |
| `--admin-token` | `IPE_AGENT_ADMIN_TOKEN` | Bearer token for list/review |
| `--submitted-by` | `IPE_AGENT_ID` | Agent identity |

Flags take priority over environment variables.

## All commands

```bash
npx @ipe-city/agents submit-app --json '<payload>' --api-url <url> [--token <t>]
npx @ipe-city/agents submit-person --json '<payload>' --api-url <url> [--token <t>]
npx @ipe-city/agents submit --kind <app|person> --json '<payload>' --api-url <url>
npx @ipe-city/agents list [--status pending|approved|rejected] [--kind app|person] --api-url <url> --admin-token <t>
npx @ipe-city/agents review <id> --status approved|rejected --api-url <url> --admin-token <t>
npx @ipe-city/agents manifest
npx @ipe-city/agents install
```

## Optional: install skill templates

If you want Codex or Claude to discover Ipe Hub capabilities automatically:

```bash
npx @ipe-city/agents install
```

This copies skill files to `~/.codex/skills/` and `~/.claude/commands/`. It is **not required** — agents can submit data without installing.

## Trusted agents

Server admins can set `IPE_TRUSTED_AGENTS=agent-id-1,agent-id-2` on the backend. Submissions from trusted agents are auto-approved and published immediately — no manual review needed. Use `--submitted-by <agent-id>` to identify your agent.