Getting Started

Agent skills are the fastest way to integrate AuraImage — install once and your AI agent handles everything: project setup, image components, upload flows, and migrations. There is also an MCP-only path and a manual aura init flow.

Option 1 — Agent Skills (recommended)

Agent skills are pre-built behaviors that train Claude Code or Cursor on AuraImage conventions. One install gives your agent judgment across the full integration surface.

1. Install skills

npx skills add auraimage/skills

Restart your agent after installing.

2. Tell your agent

"Install AuraImage in this project."

The /install-auraimage-app skill takes it from there: detects your framework, writes .env.local, registers the MCP server, installs @auraimage/sdk and the React components, and scaffolds an upload-token route. One confirm, idempotent, stops cleanly on failure.

See Agent Skills for the full skill list and what each one does.

Option 2 — MCP only

If your agent supports MCP but not skills, add the MCP server manually.

1. Add the MCP server to your project

Create or edit .mcp.json in your project root:

{
  "mcpServers": {
    "auraimage": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@auraimage/mcp-server@latest"],
      "env": {
        "AURA_SECRET_KEY": "${AURA_SECRET_KEY}"
      }
    }
  }
}

Restart your agent so the MCP server loads.

2. Tell your agent

"Install AuraImage in this project."

See AI Integration for the full MCP tool list.

Option 3 — Install manually

1. Install the CLI

npm install -g @auraimage/cli

2. Initialize your project

aura init

You'll be prompted for:

• Your project name (e.g. my-app) — appears in every image URL.
• Your Public Key (pk_*) — your project identifier; safe to expose.
• Your Secret Key (sk_live_*) — used by your backend to sign upload tokens. Never expose in client code.

Find both keys in the dashboard → Settings → API Keys.

aura init writes aura.config.json and appends three keys to .env.local:

NEXT_PUBLIC_AURA_PUBLIC_KEY=pk_...
AURA_SECRET_KEY=sk_live_...
NEXT_PUBLIC_AURA_PROJECT_NAME=my-app

To rotate keys later without losing your project name: aura init --rotate.

3. Sign in

aura login

This opens your browser, asks you to confirm a short code, and stores a CLI session at ~/.aura/credentials. The token is scoped to this machine — revoke it from Settings → CLI sessions in the dashboard at any time. Run aura logout to sign out and revoke the token.

On a headless box (CI, SSH, container), pass --no-browser and open the printed URL on a device that has a browser.

Your first upload

Server-side: mint a short-lived signature with your Secret Key.

import { AuraImage } from '@auraimage/sdk';

const aura = new AuraImage({
  secretKey: process.env.AURA_SECRET_KEY!,
  projectName: process.env.NEXT_PUBLIC_AURA_PROJECT_NAME!
});

export async function POST() {
  const signature = await aura.signUpload({
    maxSize: '5mb',
    allowedTypes: ['image/*'],
    expiresIn: 3600
  });
  return Response.json({ signature });
}

Client-side: fetch the signature, then upload directly to the AuraImage edge.

const { signature } = await fetch('/api/aura/sign', { method: 'POST' }).then((r) => r.json());

const formData = new FormData();
formData.append('file', file);
formData.append('filename', 'hero-image.jpg');

const res = await fetch('https://cdn.auraimage.ai/v1/upload', {
  method: 'POST',
  headers: { 'X-Aura-Signature': signature },
  body: formData
});

const { url, key, blurhash, width, height } = await res.json();
// url → https://cdn.auraimage.ai/my-app/abc123xyz0-hero-image.jpg

Display the image

<img src="https://cdn.auraimage.ai/my-app/abc123xyz0-hero-image.jpg?w=800&fmt=auto" alt="Hero" />

For BlurHash placeholders and automatic LCP optimization, use the <AuraImage /> component — see Components → Image.

Next steps

• Install Agent Skills to give your AI agent built-in AuraImage knowledge.
• Resize, crop, and re-format with the URL API.
• Add the <AuraUploader /> component for drag-and-drop UI.
• Gate images behind signed URLs with Private Images.
• Connect the MCP server so your agent can audit, migrate, and manage images.