@ipe-city/agents

Agent-friendly CLI for publishing and reviewing Ipê City apps, articles, people, local projects, and passport profiles.

• Package: @ipe-city/agents
• CLI: ipe-city-agents
• Repository: https://github.com/iggymtrkd/ipe-city-agents
• Current package version: 0.6.2

Why it exists

Ipê City needs contributions from people and agents to become structured data the app can trust: app listings, articles, profiles, project metadata, and passport updates. This CLI gives agents one predictable way to prepare that data, send it to the right backend, and report whether the contribution was published immediately or queued for review.

The package is designed for real agent workflows:

• Friendly flags for common updates, so agents do not have to hand-write JSON.
• --dry-run support for checking payloads before anything is sent.
• Local project scanning for app submissions.
• Authenticated passport/profile updates without exposing wallet private keys.
• Moderation and admin review commands for operators.

What this is for

Use this package when an agent or script needs to send structured contributions to Ipê City:

• Publish or update an app listing.
• Publish or update an article.
• Publish or update a person/profile listing.
• Publish a local project by reading its package.json, README, git remote, icon, and preview files.
• Help a user update or claim their Ipê passport after they authenticate in the browser.
• List or review pending submissions when you have admin credentials.

The CLI can run directly with npx; installing local helper files is optional.

Optional attribution prompts

When you run friendly commands like submit-project, update-project, submit-app, update-app, submit-person, profile, passport-claim, or update-article in an interactive terminal, the CLI asks for three optional attribution fields:

• Email address.
• Wallet address for the wallet that owns your .ipecity.eth name.
• Luma profile URL.

Press Enter to skip any field. These details help Ipê Hub populate the platform with correct user data and connect contributions to the right person for attribution, points, token drops, and future rewards.

You can also pass them directly:

npx @ipe-city/agents update-project . \
  --website-url https://example.com \
  --email [email protected] \
  --wallet-address 0x1234567890abcdef1234567890abcdef12345678 \
  --luma-url https://lu.ma/u/usr-XXXX

Use --no-attribution-prompts for non-interactive scripts that should never ask.

Install

Run it without installing:

npx @ipe-city/agents --help

Or install it globally:

npm install -g @ipe-city/agents
ipe-city-agents --help

Quick start

Publish the current project as an app:

npx @ipe-city/agents update-project . \
  --website-url https://example.com \
  --submitted-by codex-app-publisher \
  --author-name "Person Name" \
  --luma-url https://lu.ma/u/usr-XXXX

update-project reads local project metadata, captures the repository URL separately from the live app URL, and generates fallback image assets when no icon or preview is found.

Update an app directly:

npx @ipe-city/agents update-app \
  --name "Village Grants Radar" \
  --website-url https://radar.ipe.city \
  --description "Tracks live funding opportunities for builders." \
  --category earn \
  --repo-url https://github.com/org/radar \
  --submitted-by codex-app-publisher

Submit an app for moderation instead of publishing immediately:

npx @ipe-city/agents submit-app \
  --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"}'

Passport updates

For user-owned passport/profile changes, the user should create their Ipê City name and then authenticate with the same wallet:

npx @ipe-city/agents auth-guide

The correct user flow is:

1. Open https://app.ipe.city.
2. Register a .ipecity.eth name with the wallet they want to use for Ipê City.
3. Open https://ipe.city/passport.
4. Connect the same wallet that owns the .ipecity.eth name.
5. Populate the passport profile with name, bio, avatar, city, expertise, Luma, email, apps, and links.
6. Click Copy agent auth and paste the copied IPE_PASSPORT_AUTH_TOKEN export command into the terminal if an agent should update the passport.

The same-wallet step matters: the passport page needs to see the wallet that owns or resolves to the .ipecity.eth name before profile data and future attribution can be connected correctly.

After that, update the authenticated profile:

npx @ipe-city/agents profile \
  --auth-token "$IPE_PASSPORT_AUTH_TOKEN" \
  --name "Ana Builder" \
  --bio "Design systems and governance tooling." \
  --avatar ./avatar.png \
  --passport-name ana.ipecity.eth \
  --city "Florianopolis" \
  --expertise "design systems, governance" \
  --luma-url https://lu.ma/u/usr-XXXX

Claim or refresh a passport profile:

npx @ipe-city/agents passport-claim \
  --auth-token "$IPE_PASSPORT_AUTH_TOKEN" \
  --name "Ana Builder" \
  --bio "Design systems and governance tooling." \
  --avatar ./avatar.png \
  --passport-name ana.ipecity.eth \
  --luma-url https://lu.ma/u/usr-XXXX \
  --apps-json '[{"name":"Village Grants Radar","url":"https://radar.ipe.city","status":"approved"}]'

Profile and passport commands use the authenticated user token. They do not need the admin review token.

Articles and people

Publish an article immediately:

npx @ipe-city/agents update-article \
  --title "Agent Cities Need Better Public Memory" \
  --subtitle "Why moderated knowledge should be first-class infrastructure" \
  --author-name "Ana Builder" \
  --author-role "Research Lead" \
  --author-org "Ipê City" \
  --excerpt "A short overview of why article submissions matter." \
  --body "Agents need durable, reviewable writing." \
  --tag agents \
  --tag governance

Submit a person profile for moderation:

npx @ipe-city/agents submit-person \
  --name "Ana Builder" \
  --bio "Design systems and governance tooling." \
  --avatar ./avatar.png \
  --x-profile-url https://x.com/anabuilder

For long article payloads, use --file:

npx @ipe-city/agents submit-article --file ./article-submission.json

Publish vs submit

Use update-* when the change should publish immediately:

• update-app
• update-article
• update-person
• update-project
• profile / update-profile
• passport-claim

Use submit-* when the item should enter the moderation queue:

• submit-app
• submit-article
• submit-person
• submit-project

The backend may still require a submit token or authenticated user token, depending on the deployment.

Default backend

If --api-url is not provided, the CLI uses the live Ipê City Supabase backend.

Pass --api-url only when targeting another backend:

npx @ipe-city/agents update-app \
  --name "Village Grants Radar" \
  --website-url https://radar.ipe.city \
  --description "Tracks live funding opportunities for builders." \
  --api-url https://YOUR_PROJECT.supabase.co

Both forms are accepted:

• https://YOUR_PROJECT.supabase.co
• https://YOUR_PROJECT.supabase.co/functions/v1

Legacy Next.js API routes are still supported for older deployments.

Payload input

Most commands accept one of these input methods:

# Inline JSON
npx @ipe-city/agents submit-app --json '{"name":"..."}'

# JSON file
npx @ipe-city/agents submit-app --file ./payload.json

# stdin
echo '{"name":"..."}' | npx @ipe-city/agents submit-app

Commands such as update-app, profile, and update-article also accept friendly flags so agents do not have to hand-write JSON for common tasks.

Common flags

| Flag | Environment variable | Purpose | | --- | --- | --- | | --api-url | IPE_AGENT_API_BASE_URL | API base URL. Optional for the live Ipê City backend. | | --token | IPE_AGENT_SUBMIT_TOKEN | Submit/publish bearer token when the backend requires one. | | --auth-token | IPE_PASSPORT_AUTH_TOKEN | User token for passport and authenticated update flows. | | --admin-token | IPE_AGENT_ADMIN_TOKEN | Admin token for list/review commands. | | --submitted-by | IPE_AGENT_ID | Agent identity included with submissions. | | --dry-run | | Print the request body without sending it. | | --email | IPE_AGENT_USER_EMAIL | Optional user email for attribution, points, and future rewards. | | --wallet-address | IPE_AGENT_WALLET_ADDRESS | Optional wallet address for the user's .ipecity.eth name. | | --luma-url | IPE_AGENT_LUMA_URL | Optional Luma profile URL for attribution. | | --no-attribution-prompts | | Skip optional attribution questions. |

Project author defaults:

| Environment variable | Purpose | | --- | --- | | IPE_AGENT_AUTHOR_NAME | Default author display name for submit-project and update-project. | | IPE_AGENT_AUTHOR_AVATAR | Default author avatar path or URL. | | IPE_AGENT_LUMA_URL | Default Luma profile URL. |

Data shapes

App payloads require:

| Field | Description | | --- | --- | | name | App name. | | websiteUrl | Live app URL. This is not the source repository. | | iconUrl | HTTP(S), ipfs://, or data:image/... image. | | previewImageUrl | HTTP(S), ipfs://, or data:image/... image. | | description | What the app does. |

Useful optional app fields include category, tags, repoUrl, and authors.

Person/profile payloads require name, bio, and avatarUrl when using the profile-style flag commands. Useful optional fields include passportName, city, expertise, lumaUrl, instagramUrl, xProfileUrl, linkedInUrl, websiteUrl, and apps.

Article payloads require title, subtitle, authorName, authorRole, authorOrg, excerpt, and at least one section with heading and body. publishedAt, tags, coverUrl, and authorAvatarUrl are optional. When using update-article flags, the CLI defaults publishedAt to today and builds the first section from --body.

Admin commands

List submissions:

npx @ipe-city/agents list \
  --status pending \
  --admin-token "$IPE_AGENT_ADMIN_TOKEN"

Approve or reject a submission:

npx @ipe-city/agents review <submission-id> \
  --status approved \
  --admin-token "$IPE_AGENT_ADMIN_TOKEN"

Optional local install

Install Codex and Claude helper files:

npx @ipe-city/agents install

This writes:

• ~/.codex/skills/ipe-city-submit/SKILL.md
• ~/.claude/commands/ipe-city-submit.md
• ~/.ipe-city/agents/manifest.json

You can inspect the installed capability contract with:

npx @ipe-city/agents manifest

Development

This repository is intentionally small: the CLI lives in bin/ipe-city-agents.js, package metadata lives in package.json, and agent helper templates live in templates/.

Useful local checks:

node bin/ipe-city-agents.js --help
npm pack --dry-run --json
node bin/ipe-city-agents.js update-app \
  --name "Village Grants Radar" \
  --website-url https://radar.ipe.city \
  --description "Tracks live funding opportunities for builders." \
  --dry-run

Before publishing, confirm package.json points at the maintained repository:

{
  "repository": {
    "url": "git+https://github.com/iggymtrkd/ipe-city-agents.git"
  }
}

License

MIT