> ## Documentation Index
> Fetch the complete documentation index at: https://docs.uselamina.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Use The CLI And SDK

> How to run Lamina from a terminal, save an API key, inspect apps, execute jobs, and understand where the SDK fits today.

## Choose The Right Integration Surface

Lamina supports three developer entry points:

| Surface    | Best for                                                           | What it does                                                             |
| ---------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------ |
| HTTP API   | Backends and production services                                   | Call `/v1` directly from your own code                                   |
| CLI        | Terminal workflows and manual testing                              | Save an API key, inspect apps, run executions, receive webhook callbacks |
| MCP server | Coding agents such as Claude Code, Cursor, and desktop MCP clients | Expose Lamina as tools an agent can call                                 |

The HTTP API is the canonical contract. The CLI and MCP server are thin wrappers around that same `/v1` surface.

## Install From npm

```bash theme={null}
npm install @uselamina/sdk
npm install -g @uselamina/cli
```

If you want to run the MCP server without a global install:

```bash theme={null}
npx -y @uselamina/mcp
```

If you prefer a global MCP binary:

```bash theme={null}
npm install -g @uselamina/mcp
lamina-mcp
```

## Authenticate Once

`lamina login` opens your browser for an OAuth approval flow — pick a workspace, click **Approve**, and the CLI receives the token on a loopback callback.

```bash theme={null}
lamina login
```

For CI / scripted callers, pass a workspace API key non-interactively:

```bash theme={null}
lamina login --api-key lma_your_api_key
```

Either path stores credentials at `~/.lamina/config.json` (mode `0600`). OAuth tokens auto-refresh near expiry — you stay logged in for up to 30 days without re-prompting.

Inspect the active identity at any time:

```bash theme={null}
lamina whoami
```

Or skip local storage entirely and use the environment:

```bash theme={null}
export LAMINA_API_KEY=lma_your_api_key
```

The CLI and MCP server resolve auth in this order:

1. `LAMINA_API_KEY` environment variable
2. saved CLI credentials at `~/.lamina/config.json` (OAuth tokens or API key)

Sign out:

```bash theme={null}
lamina logout
```

## Inspect Apps

List available apps:

```bash theme={null}
lamina apps list --search catalog
```

Inspect one app's parameter contract:

```bash theme={null}
lamina apps get <appId>
```

## Upload A Local File

Pass a path; the CLI streams the bytes to Lamina's CDN via a pre-signed URL and prints the resulting URL you can pass to `lamina run --input ...`:

```bash theme={null}
URL=$(lamina assets upload ./me.jpg --json | jq -r '.data.url')
```

## Run An App

You can run with a JSON file:

```bash theme={null}
lamina run <appId> --file inputs.json --wait
```

Or inline values:

```bash theme={null}
lamina run <appId> \
  --input "Your photo=https://example.com/selfie.png" \
  --input "Celebrity Name=Anne Hathaway" \
  --input "Aspect Ratio=1:1" \
  --wait
```

The CLI fetches the app schema first and validates:

* unknown parameter names
* missing required inputs
* invalid option labels
* invalid `url` values

## Where The SDK Fits

The shared Lamina client is published as `@uselamina/sdk` and powers both the CLI and MCP server.

If you are integrating from your own backend, use `@uselamina/sdk` or call the `/v1` HTTP API directly.

The client wraps:

* `GET /v1/apps`
* `GET /v1/apps/{appId}`
* `GET /v1/apps/{appId}/workflow`
* `POST /v1/apps/{appId}/runs`
* `GET /v1/runs/{runId}`
* `GET /v1/webhooks/signing-key`

## Next Steps

* Read [Test Webhooks Locally](/guides/test-webhooks-locally) to receive signed Lamina callbacks on your machine
* Read [Agent Integration Patterns](/guides/agent-integration-patterns) to run Lamina through MCP in coding agents
* Read [Quick Start](/quick-start) if you want to stay on the raw HTTP API