@vadenai/sdk

Vaden CLI — scan, validate, and sync .uxir files with the Vaden platform.

Installation

# Global install
npm install -g @vadenai/sdk

# Or run directly with npx
npx @vadenai/sdk <command>

# Or with pnpm
pnpm add -g @vadenai/sdk

Quick Start

# 1. Authenticate with your Vaden Registry Token
vaden login --token "<your-token>"

# 2. Initialize project configuration
vaden init

# 3. Scan your codebase and generate .uxir files
vaden scan ./apps/my-app --output .uxir

# 4. Push to the Vaden Dashboard
vaden push

Commands

vaden login

Authenticate with the Vaden platform. Credentials are saved to ~/.vaden/credentials.json.

vaden login --token "<your-token>"   # Pass token directly
vaden login                          # Enter token interactively
vaden login --api-url <url>          # Use a custom API URL

| Option | Description | | ----------------- | --------------------------------------------------- | | --token <token> | Registry Token issued from Dashboard > Settings > Tokens | | --api-url <url> | Custom API endpoint (default: https://app.vaden.ai) |

vaden init

Create the project configuration file .vaden/config.json in the current directory.

vaden init                  # Default output directory (.uxir)
vaden init --output .uxir   # Specify output directory

| Option | Description | | ------------------ | ---------------------------------------------------- | | --output <dir> | Output directory for generated .uxir files (default: .uxir) |

vaden scan

Analyze a Next.js App Router project, extract screens, transitions, and UI components, then generate .uxir files.

vaden scan <dir>                     # Basic scan
vaden scan <dir> --output .uxir      # Specify output directory
vaden scan <dir> --enrich            # Infer intent/states via LLM (requires ANTHROPIC_API_KEY)
vaden scan <dir> --json              # Output as WireframeData JSON instead of .uxir
vaden scan <dir> --validate          # Validate generated files after scanning

| Option | Description | | ---------------- | ------------------------------------------------------------------------------- | | --output <dir> | Output directory for generated .uxir files (default: .uxir) | | --enrich | Use LLM to infer screen intent, states, and transitions (requires ANTHROPIC_API_KEY) | | --json | Output scan result as WireframeData JSON (stdout) | | --validate | Run schema validation on generated .uxir files after scanning |

What gets scanned

| Target | Detection method | | ----------- | ----------------------------------------------------------------------------------- | | Screens | page.tsx / page.jsx files under app/ (redirect-only pages excluded) | | Transitions | Usages of Link, router.push, and redirect | | Components | JSX tag pattern matching (button, input, card, table, and 15+ more types) | | Groups | Route groups (group) are detected and .uxir files are split per group |

Component types extracted

button, input, table, form, card, modal, tabs, nav, sidebar, header, footer, avatar, badge, breadcrumb, search, image, link, chart, text

--enrich option (LLM inference)

Requires the ANTHROPIC_API_KEY environment variable. Runs a two-phase analysis:

| Phase | What it does | Output | | --------------------------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | | Phase 1: Intent / States / Transitions | Infers purpose, UI states, and transitions from each screen's source code | purpose, designSpec.states, additional transitions | | Phase 2: Layout inference | Infers component positions and state-conditional visibility from the expanded source (imports included) | components[].x/y/width/height/visibleIn |

Estimated cost: ~$0.30/scan with Sonnet, ~$0.03/scan with Haiku (22-screen project).

vaden push

Send all .uxir files to the Vaden Dashboard.

vaden push

Uploads to POST /api/projects/[id]/uxir. The server parses the UXIR YAML, merges screens and transitions across multiple files, converts to WireframeData, and persists to the wireframe tab.

vaden validate

Validate .uxir files against the schema.

vaden validate <dir|file>
vaden validate .uxir --json     # Output results as JSON
vaden validate .uxir --strict   # Treat warnings as errors

| Option | Description | | ---------- | --------------------------------------- | | --json | Output validation results as JSON | | --strict | Treat warnings as errors (exit code 1) |

vaden generate

Generate .uxir files from a WireframeData JSON file.

vaden generate wireframe.json --output .uxir

| Argument | Description | | ----------------- | -------------------------------------------------------- | | <json-file> | Path to a WireframeData JSON file | | --output <dir> | Output directory for generated .uxir files (default: .uxir) |

UXIR Format

UXIR (UX Intermediate Representation) is a YAML DSL for describing screen structure.

version: 1
screens:
  - id: login
    intent: User authentication screen
    title: Login
    components:
      - type: input
        label: Email address
      - type: input
        label: Password
      - type: button
        label: Log in
    states:
      - id: default
        title: Initial view
      - id: error
        title: Error view
  - id: dashboard
    intent: Main dashboard
    title: Dashboard

transitions:
  - from: { screen: login }
    event: Login successful
    to: { screen: dashboard }

Schema

| Field | Type | Required | Description | | ------------- | ------------ | -------- | ----------------------------------- | | version | number | Yes | Schema version (currently 1) | | screens | Screen[] | Yes | Array of screen definitions | | transitions | Transition[] | Yes | Array of screen transition definitions |

Screen

| Field | Type | Required | Description | | ------------ | ----------- | -------- | -------------------------------------------------- | | id | string | Yes | Unique snake_case ID (/^[a-z][a-z0-9_]*$/) | | intent | string | Yes | Purpose and role of the screen | | title | string | No | Display title | | states | State[] | No | List of UI states for this screen | | components | Component[] | No | List of UI components on this screen |

Component

| Field | Type | Required | Description | | ----------- | -------- | -------- | -------------------------------------------------------- | | type | string | Yes | Component type (button, input, card, etc.) | | label | string | Yes | Descriptive label | | x | number | No | X position (inferred by --enrich) | | y | number | No | Y position | | width | number | No | Width | | height | number | No | Height | | visibleIn | string[] | No | State IDs where this component is visible (all states if omitted) |

Transition

| Field | Type | Required | Description | | ------- | -------------------- | -------- | -------------------- | | from | { screen: string } | Yes | Source screen | | event | string | Yes | Trigger event | | to | { screen: string } | Yes | Destination screen |

Authentication

The CLI uses a Registry Token (JWT) issued from the Vaden Dashboard.

1. Go to Dashboard > Settings > Registry Token and issue a token
2. Run vaden login --token "<your-token>" to authenticate
3. The token is stored in ~/.vaden/credentials.json

Configuration Files

~/.vaden/credentials.json

{
  "token": "eyJhbG...",
  "apiUrl": "https://app.vaden.ai"
}

.vaden/config.json

{
  "projectId": "project-uuid",
  "outputDir": ".uxir"
}

Security Best Practices

• Never commit tokens to Git — Add ~/.vaden/credentials.json to your .gitignore if copied into a project directory
• Use environment variables for CI — Pass VADEN_TOKEN as an environment variable rather than storing it in files checked into version control
• Protect your ANTHROPIC_API_KEY — Required for --enrich; never hardcode it in scripts
• Rotate tokens regularly — Issue new tokens from Dashboard > Settings > Tokens and revoke old ones
• If a token leaks — Revoke it immediately from the Dashboard

Requirements

| Requirement | Version | | ----------- | -------- | | Node.js | >=18.18 |

License

MIT