# Getting Started (https://auraimage.ai/docs/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) [#option-1--agent-skills-recommended]

[Agent skills](/docs/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 [#1-install-skills]

```bash
npx skills add auraimage/skills
```

Restart your agent after installing.

### 2. Tell your agent [#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](/docs/skills) for the full skill list and what each one does.

## Option 2 — MCP only [#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 [#1-add-the-mcp-server-to-your-project]

Every agent reads MCP config from its own file, in its own shape — [AI Integration](/docs/ai-integration) carries the exact block for each one. The server itself is the same everywhere: `npx -y @auraimage/mcp-server@latest`, reading your key from `AURA_SECRET_KEY`. Claude Code's version, for example:

```json title=".mcp.json (Claude Code)"
{
  "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 [#2-tell-your-agent-1]

> Install AuraImage in this project.

See [AI Integration](/docs/ai-integration) for the full MCP tool list.

## Option 3 — Install manually [#option-3--install-manually]

### 1. Install the CLI [#1-install-the-cli]

```bash
npm install -g @auraimage/cli
```

### 2. Initialize your project [#2-initialize-your-project]

```bash
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](https://app.auraimage.ai) → Settings → API Keys.

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

```bash title=".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 [#3-sign-in]

```bash
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 [#your-first-upload]

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

```ts title="app/api/aura/sign/route.ts"
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: '30mb',
    allowedTypes: ['image/*'],
    expiresIn: 3600
  });
  return Response.json({ signature });
}
```

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

```ts
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, name, blurhash, width, height } = await res.json();
// url → https://cdn.auraimage.ai/my-app/abc123xyz0-hero-image
```

## Display the image [#display-the-image]

```tsx
<img src="https://cdn.auraimage.ai/my-app/w=800/abc123xyz0-hero-image" alt="Hero" />
```

For BlurHash placeholders and automatic LCP optimization, use the `<AuraImage />` component — see [Components → Image](/docs/image).

## Next steps [#next-steps]

* Install [Agent Skills](/docs/skills) to give your AI agent built-in AuraImage knowledge.
* Resize, crop, and re-format with the [URL API](/docs/url-api).
* Add the [`<AuraUploader />` component](/docs/uploader) for drag-and-drop UI.
* Gate images behind signed URLs with [Private Images](/docs/private-images).
* Connect the [MCP server](/docs/ai-integration) so your agent can audit, migrate, and manage images.


## Related

- [Agent Skills](https://auraimage.ai/docs/skills)
- [Upload Flow](https://auraimage.ai/docs/upload)
- [Local Development](https://auraimage.ai/docs/local-development)