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.

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. Authentication is your Bearer API key.

npx add-mcp https://argus.build/mcp

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

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

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}'