Quick Start

Argus is an AI-native media library. The fastest way in is the CLI and MCP — you can get an agent working against a real library without writing a single HTTP request. API-first? Skip to the API Quickstart.

Everything below needs an API key. Grab one first — it takes about a minute: Get an API key. Then export ARGUS_API_KEY=ak_yourkey so the CLI and MCP pick it up.

1. Point the CLI at a library

Install the CLI, then choose your starting point:

npm install -g argus-media-cli
argus-media-cli login

Joining an existing library? Pull its design context into your working folder. init writes an .argus/ folder with the project's palette, type, and brand notes so your agent has real context to work from — zero credits, read-only.

argus-media-cli init brand-2019

Onboarding a brand folder? Push it in one shot. sync walks the folder, skips junk and duplicates, uploads the rest, and drops the same agent context on the way out.

argus-media-cli sync ./legacy-brand-folder --dry-run   # preview the plan
argus-media-cli sync ./legacy-brand-folder --project brand-2019

2. Wire up your agent

Give your agent live access to the library over MCP, and install the Argus skills so it knows the workflows.

# hosted MCP — full tool set, always current
npx add-mcp https://argus.build/mcp

# install the agent skills into ~/.claude/skills
npx argus-media-cli skills install

See MCP Setup for editor config and the tool list. Restart your agent session, then trigger a skill explicitly for determinism: "use the argus-brand-onboarding skill to onboard this brand folder into Argus."

3. Explore the library

Ask your agent to scope the library, then search it. Under the hood these map to get_library_overview and search_assets — or run them from the terminal:

argus-media-cli list --project brand-2019
argus-media-cli search "warm golden-hour hero shot"

That's the whole loop: point at a library, wire up the agent, search. No HTTP required. The API Reference below covers the raw REST surface for when you need it.

Get an API Key

Every request — CLI, MCP, or raw REST — authenticates with a Bearer API key.

Create a key

1. Go to argus.build/ui
2. Sign in with a magic link (email-based, no password)
3. Open Settings
4. Click Create API Key

Then hand it to whichever surface you're using:

# CLI and MCP read it from the environment
export ARGUS_API_KEY=ak_yourkey

# raw REST passes it as a Bearer token
curl https://argus.build/assets -H "Authorization: Bearer ak_yourkey"

Session auth (cookie-based) is used by the web UI. API keys are for agents and scripts. You can also mint keys programmatically with the create_api_key MCP tool or argus-media-cli keys create.

Command Line

The argus-media-cli package gives you terminal access to onboard folders, pull design context, search, and manage assets. It's the front door for both humans and agents.

npm install -g argus-media-cli
argus-media-cli login

login saves your key; you can also set ARGUS_API_KEY (and ARGUS_BASE_URL to self-host) in the environment. Add --json to any command for machine-readable output.

init — pull a project

Direction: Argus → your folder. Bind the current folder to an existing project and pull its design context so an agent has real brand material to work from. init writes an .argus/ folder — a DESIGN-CONTEXT.md (palette, typography, brand notes) plus an AGENTS.md primer — and is idempotent and zero-credit.

argus-media-cli init brand-2019

Called with no project — or an unknown one — init lists the available projects and exits non-zero (handy in scripts with --json). Pass --no-agent-setup to write .argus/ context but skip the skills/MCP prompt.

sync — push a folder

Direction: your folder → Argus. Onboard an entire folder in one shot — perfect for migrating a legacy brand folder. sync walks the folder recursively, skips junk and duplicates, uploads the rest sequentially, prints a manifest, and drops the same .argus/ agent context on the way out.

argus-media-cli sync ./legacy-brand-folder --dry-run
argus-media-cli sync ./legacy-brand-folder --project brand-2019 --tags legacy

Uploads JPEG/PNG/GIF/WebP/SVG up to 20 MB. Skips junk files (.DS_Store, Thumbs.db, hidden dotfiles), unsupported types, oversize files, and duplicates (by content hash, and by filename + size already in the target project). The project defaults to the kebab-cased folder name. Flags: --dry-run previews the plan, --json emits a structured manifest, --yes proceeds past a credit-shortfall warning unattended, --no-agent-setup skips the context drop.

Brand-fit search

Rank search and list results by how closely each asset's colors match a target brand palette. Pass --palette-fit a style-guide id or a project name; every result gains a fitScore (0–1) and off-palette assets sort last. Add --min-fit to drop anything below a threshold.

argus-media-cli search "hero background" --palette-fit brand-2019 --min-fit 0.6

The same ranking is available on the REST endpoint (GET /assets?paletteFit=…) and the search_assets MCP tool (palette_fit).

Curator Mode — control what agents retrieve

Every asset carries an agentRetrievable flag. Retrievable assets (the default) are visible to agent-facing MCP retrieval; hidden assets stay on the human/UI path but are invisible to search_assets, get_asset, and get_library_overview. Curate work-in-progress, off-brand, or internal assets out of your agents' reach without deleting them. Toggling is an editor+ action; a viewer key can never retrieve a hidden asset by any means.

argus-media-cli curator status
argus-media-cli curator hide "./drafts/*" --note "work in progress"
argus-media-cli curator approve logo-final.svg
argus-media-cli sync ./new-drop --project brand-2019 --curator-default hidden

Globs resolve client-side against local filenames, then look up ids via the catalog (filename + --project) — renamed or deduped files may not resolve, so pass explicit ids there. REST: PATCH /assets/:id/curator, POST /assets/curator/bulk, GET /assets/curator/summary, GET /assets/:id/curator/history, and ?agentRetrievable=true|false on GET /assets (editor+ only for false). Admins set the workspace default for new uploads with PUT /workspaces/:id/curator-default; changing it never touches existing assets.

Install the agent skills

Argus ships two Claude agent skills — argus (the API/MCP operating manual) and argus-brand-onboarding (the end-to-end legacy-folder → brand-system arc). They're bundled with the CLI; install them into your Claude skills directory in one shot:

npx argus-media-cli skills install

Files land at ~/.claude/skills/<name>/SKILL.md (override with --dir). It's idempotent — re-running overwrites with newer content. Restart your Claude/agent session so it picks the skills up, then trigger one explicitly for determinism: "use the argus-brand-onboarding skill to onboard this brand folder into Argus." Brand onboarding's cohesion, style-guide, and creative-direction stages run through the MCP server.

MCP Setup

Give your agent direct access to Argus over the Model Context Protocol. There are two ways to connect.

Already working inside a coding agent (Claude Code, Codex, Cursor)? Skip everything below and just say:

Fetch and execute the appropriate instructions to set me up for Argus from https://argus.build/agent-setup/prompt.md

The agent fetches that page and runs it unattended — no token to copy in first, no visit to the library toolbar required. It leads with the OAuth flow below, so a browser tab is all it needs. Not working in a coding agent? See Chat assistants.

Hosted server (recommended)

Connect to the hosted MCP endpoint at https://argus.build/mcp. It exposes the full tool registry, stays current automatically, and needs nothing installed — there is no package to resolve and no version to keep in step.

claude mcp add --transport http argus https://argus.build/mcp --header "Authorization: Bearer at_YOUR_TOKEN"

Which token?

at_ — agent session token. Short-lived (4, 8, or 24 hours), bound to one workspace, revocable, and unable to escalate: it cannot mint API keys, manage members, or touch billing. This is the only token safe to paste into a chat transcript. Mint one from the library toolbar → Connect agent, which copies a complete block containing the command, the token, and a verify step.

ak_ — API key. Durable, no expiry. Use it in environment variables and CI. Never paste one into a chat transcript: it does not expire, so it stays valid there for as long as the key lives.

Verify a token immediately

MCP tools only load at the next session start, so use the REST endpoint to confirm access right away. It returns the workspace the token reaches, the scope it carries, and when it expires.

curl -s https://argus.build/auth/me -H "Authorization: Bearer at_YOUR_TOKEN"

If the token is expired or revoked the response carries a remediation field naming the fix, alongside a stable code you can branch on.

Browser sessions: skip the credential entirely

Omit the header and the client runs the OAuth flow instead, so no secret ever enters the transcript. Prefer this whenever a browser is available.

claude mcp add --transport http argus https://argus.build/mcp

Or configure it by hand — for example in claude_desktop_config.json:

{
  "mcpServers": {
    "argus": {
      "type": "http",
      "url": "https://argus.build/mcp",
      "headers": { "Authorization": "Bearer at_YOUR_TOKEN" }
    }
  }
}

Chat assistants (no terminal)

Not writing code — just chatting with an AI assistant in a browser tab (Claude.ai, ChatGPT)? You don't need any of the commands above. Most chat clients let you add a custom connector by URL from their own settings, which reaches the exact same OAuth login Argus uses everywhere else:

1. Open your assistant's settings and find Connectors (or "Add custom connector" / "Add from URL").
2. Paste https://argus.build/mcp and click Connect.
3. You'll land on an Argus sign-in page — log in (or create a free workspace) and approve.

No key or token ever needs to be pasted into the chat — the sign-in happens on Argus's own page. Full walkthrough: argus.build/agent-setup.

Local stdio server

Prefer a locally-run server — or need to upload files straight off your disk? npx argus-media-mcp runs over stdio and adds argus_upload (upload a local file by path, which the hosted server can't reach). Set your key with ARGUS_API_KEY.

{
  "mcpServers": {
    "argus": {
      "command": "npx",
      "args": ["argus-media-mcp"],
      "env": { "ARGUS_API_KEY": "ak_yourkey" }
    }
  }
}

Set ARGUS_BASE_URL to override the default https://argus.build if self-hosting. The stdio package ships the core toolset plus argus_upload; the hosted endpoint carries the newest tools (library overview, palette adaptation, cross-project links, design-context export). When in doubt, use the hosted server.

MCP Tools

The hosted server exposes the full registry below. Required parameters are highlighted; everything else is optional.

Search & library

Upload & lifecycle

Brand & design

Cross-project links

Moderation & account

Library Overview

Scope a whole library in one call instead of paging through search results. GET /library/overview returns totals (asset count + storage bytes), counts by project, media type, status, and approval state, the top tags with counts, and a compact list of recent uploads. It's the fastest way for an agent to decide where to look before it searches. Also available as the get_library_overview MCP tool.

curl "https://argus.build/library/overview?top_tags=15&recent=5" \
  -H "Authorization: Bearer ak_yourkey"

Design Context Export

Turn a persisted style guide into portable, agent-ready brand context. GET /style-guides/:id/design-context renders an impeccable-compatible ## Design Context markdown block — palette (as OKLCH), typography, brand voice, layout-implied spacing and radius under a ### Design Tokens sub-block, plus anti-references drawn from cohesion outliers. Drop it into an .impeccable.md, hand it to /impeccable, or paste it into an agent prompt. Free, no credits.

The .argus/DESIGN-CONTEXT.md that argus-media-cli init writes is built from the same export, so a freshly-initialized folder already carries the project's design context.

Recolor an SVG to a Palette

Snap an SVG's colors to a target brand palette. POST /assets/:id/adapt-palette rewrites every painted color to the nearest color in the palette — a deterministic string transform over the SVG source, zero AI credits. currentColor, none/transparent, and url(#…) paint-server refs are preserved; colors it can't resolve are left in place and reported. By default it saves the result as a new derived asset carrying derivedFrom provenance — the source is never modified. Pass save: false to preview without persisting.

curl -X POST https://argus.build/assets/ASSET_ID/adapt-palette \
  -H "Authorization: Bearer ak_yourkey" \
  -H "Content-Type: application/json" \
  -d '{"paletteFit": "brand-2019", "save": true}'

Cross-Project Links

Reuse one asset across many projects without duplicating it. Links are non-destructive many-to-many membership: an asset keeps its origin project and simply becomes visible in the additional projects you link it into. GET /assets/:id returns the origin as project and any additional projects in linkedProjects.

API Quickstart

Prefer raw HTTP? The full REST surface is below. This is the classic upload → poll → search loop with curl. Everything the CLI and MCP do is built on these endpoints.

1. Upload

curl -X POST https://argus.build/assets/upload \
  -H "Authorization: Bearer ak_yourkey" \
  -F "file=@product-photo.jpg" \
  -F "project=spring-campaign" \
  -F "tags=product,lifestyle"

2. Check status

curl https://argus.build/assets/ASSET_ID \
  -H "Authorization: Bearer ak_yourkey"
# status: "pending" → "ready" once analysis completes

3. Search

curl "https://argus.build/assets?q=lifestyle+product" \
  -H "Authorization: Bearer ak_yourkey"

Assets

Upload, search, analyze, and delete media assets. Requires Bearer API key.

Soft delete & recovery: DELETE /assets/:id is a soft delete. The asset is hidden from default listings but can be recovered within 30 days via POST /assets/:id/recover. To list deleted assets, pass status=deleted on GET /assets. After 30 days, a scheduled purge permanently removes the asset and file.

Search & Response Envelopes

List and search responses are wrapped in a pagination envelope — check hasMore and page with offset rather than assuming the first page is the whole library.

// GET /assets  → list envelope
{ "assets": [ /* ... */ ], "total": 214, "limit": 50, "offset": 0, "hasMore": true }

// GET /assets/:id  → single-asset envelope
{ "asset": { /* ... */ } }

Detail levels

The search_assets MCP tool accepts a detail parameter so browsing stays cheap at scale:

• summary (default)Compact per-asset fields — id, filename, project, tags, and a one-line description. Ideal for scanning a large library.
• fullThe complete asset object, including the full analysis block.

Search semantics

The q parameter performs keyword matching across AI-generated fields — not vector search. Your query is split into terms, each matched (case-insensitive substring) against filename, description, rich description, mood, tags, and use-cases; results rank by how many terms match. It feels semantic because the fields being searched are AI-generated. Use descriptive, natural-language terms for best results.

Auth

Email-based magic link authentication. No password required. All routes are public.

Workspaces

Manage workspaces and team members. Requires session cookie (web UI auth).

API Keys

Create and revoke API keys for programmatic access. Requires session cookie.

Billing

Subscription upgrades and credit pack purchases via Stripe. Checkout routes are public; usage requires auth.

Response Shape

Every asset returned from the API includes this structure once analysis is complete.

{
  "id": "uuid",
  "filename": "photo.jpg",
  "mimeType": "image/jpeg",
  "url": "https://...",
  "status": "ready",
  "tags": ["outdoor", "nature"],
  "analysis": {
    "description": "A field of wildflowers at golden hour",
    "richDescription": "Detailed paragraph...",
    "mood": "serene",
    "dominantColors": [{ "hex": "#f5c842", "name": "golden yellow" }],
    "useCases": ["hero image", "seasonal campaign"],
    "tags": ["wildflowers", "golden hour", "landscape"]
  }
}

Field Notes

• tagsMerged array of user-supplied tags and AI-generated tags (deduplicated).
• analysis.tagsAI-generated tags only.

Error Responses

All error responses return a JSON object with an error string:

{ "error": "Description of what went wrong" }

Rate Limits

Argus uses tier-based limits (asset count and credits per month) rather than per-IP rate limiting.

• When limits are hitThe API returns 429 with { "error": "...", "upgrade": true }. Check GET /usage for current consumption.
• No per-IP throttlingThere is no request-per-second or per-IP rate limit. You can call the API as fast as needed within your tier.
• Monthly resetCredit usage resets at the start of each billing cycle. One-time credit packs do not expire.

agents.txt

Machine-readable capability declaration at /agents.txt. Plain text, no auth required. Contains the full API reference, MCP tools, pricing, and limitations in a format optimized for LLM consumption.

Supported Formats

• AI-analyzed formatsJPEG, PNG, GIF, WebP, SVG — these are processed by AI vision and receive full analysis (description, mood, colors, tags, use-cases)
• Other file typesAny file can be uploaded and stored, but non-image files (PDFs, documents, etc.) are not analyzed. They are stored in R2 and immediately set to status: "ready" with no analysis data.
• Video uploadsSupported (video/*, e.g. MP4/MOV/WebM) for accounts with the video-uploads flag enabled (default off). Not analyzed.
• Max upload size20 MB per file (images); 10 MB per file for video
• StorageCloudflare R2
• Analysis outputDescription, rich description, mood, dominant colors (hex + name), use-cases, tags, EXIF when available

Processing Time & Polling

AI analysis runs asynchronously after upload. The asset is returned immediately with status: "pending".

• Typical analysis time5–15 seconds for most images
• How to checkPoll GET /assets/:id until status changes to "ready" or "error". Recommended interval: every 2–3 seconds.
• WebhooksNot available. Polling is the only option.

Pricing

1 credit = 1 AI image analysis. Credit packs: 100 for $2, 500 for $8, 2,500 for $30.

When NOT to Use Argus

• Video filesSupported only for accounts with the video-uploads flag enabled, capped at 10 MB. No analysis, no storage optimization.
• Real-time processingAnalysis is async. Not suitable for synchronous pipelines.
• Non-image documentsPDFs, docs, spreadsheets are stored but never analyzed.
• Self-hosted storageArgus uses Cloudflare R2. No bring-your-own-bucket option.
• Bulk migrationNo batch upload API. Use the CLI's argus-media-cli sync <folder> command to onboard a whole folder (it walks, filters junk/dupes, and uploads sequentially), or loop over /assets/upload yourself.