CLI Tool

The Aether CLI (@aether-official/cli) provides command-line tools for working with the Aether Sites SDK. The primary feature is automatic TypeScript type generation from your CMS schema, giving you full autocomplete and type safety when fetching content.

Installation

Install the CLI as a dev dependency in your project:

npm install -D @aether-official/cli

The CLI is available as the aether-sdk command via npx:

npx aether-sdk --help

Commands

init - Interactive Setup

Initialize Aether SDK in your project with an interactive wizard:

npx aether-sdk init

The wizard will:

1. Prompt for your credentials (Site ID, Organization ID, API Token, API URL)
2. Test the connection to verify credentials
3. Create a .env file with your configuration
4. Fetch your site’s schema
5. Generate TypeScript types

Example:

$ npx aether-sdk init

🚀 Initializing Aether Sites SDK...

◇  Site ID:
│  cmhwjphho001uknr2ohzn6m3e
│
◇  Organization ID:
│  cmgwxbxga0006fxjdbnikdxg3
│
◇  API Token:
│  ********************************
│
◇  API URL (optional):
│  http://localhost:3000

🔍 Testing connection...
✅ Connected successfully!
   Found 5 section templates

✅ Created .env file
✅ Schema saved to .aether/schema.json
✅ Types generated: src/aether-types.d.ts

sync - Fetch Schema

Fetch the latest schema from your CMS:

npx aether-sdk sync

This downloads all section templates and their fields from your Aether CMS and saves them to .aether/schema.json.

When to use:

• After creating new section templates in the visual editor
• After adding/removing fields from templates
• When switching between sites or environments

Output:

📡 Fetching site schema...
✅ Found 5 section templates
✅ Schema saved to .aether/schema.json

Templates:
  • Hero Section (8 fields)
  • Features Grid (4 fields)
  • Testimonials (3 fields)
  • Call to Action (5 fields)
  • Footer (6 fields)

types - Generate TypeScript Types

Generate TypeScript type definitions from your schema:

npx aether-sdk types

This reads .aether/schema.json and generates src/aether-types.d.ts with:

• Section ID constants
• TypeScript interfaces for each section’s data
• Helper types for type-safe content fetching

Output:

🔨 Generating TypeScript types...
✅ Types generated: src/aether-types.d.ts
   Generated 5 section types

Example usage:
  import { SECTIONS } from './aether-types';
  import { fetch } from '@aether-official/sites-sdk/astro';

  const section = await fetch.section(SECTIONS.HERO);

Configuration

Environment Variables

The CLI reads configuration from your .env file:

.env

AETHER_SITE_ID=your-site-id
AETHER_ORGANIZATION_ID=your-org-id
AETHER_API_TOKEN=your-api-token
AETHER_API_URL=http://localhost:3000

Getting Your Credentials

1. Site ID & Organization ID: Found in your Aether dashboard URL or site settings
2. API Token: Generate in Aether Settings → API Tokens
3. API URL:
   • Development: http://localhost:3000
   • Production: https://your-aether-instance.com

Generated Types

The CLI generates a src/aether-types.d.ts file with full TypeScript definitions:

Section ID Constants

export const SECTIONS = {
  HERO: 'cmhwjphho001uknr2ohzn6m3e' as const,
  FEATURES: 'abc123def456' as const,
  TESTIMONIALS: 'xyz789' as const,
} as const;

Use these instead of hardcoding IDs:

// ❌ Bad - hardcoded string
const hero = await fetch.section('cmhwjphho001uknr2ohzn6m3e', config);

// ✅ Good - type-safe constant
const hero = await fetch.section(SECTIONS.HERO, config);

Section Data Interfaces

export interface HeroData {
  /** text field */
  title: string;
  /** textarea field */
  subtitle?: string;
  /** image field */
  backgroundImage: ImageField;
  /** repeater field */
  features: Array<{
    icon: string;
    text: string;
  }>;
}

Helper Types

// Get the data type for a specific section ID
type HeroData = SectionData<typeof SECTIONS.HERO>;

// Union of all section IDs
type SectionId = typeof SECTIONS[keyof typeof SECTIONS];

Field Type Mapping

The CLI automatically maps CMS field types to TypeScript:

CMS Field Type	TypeScript Type
Text	string
Textarea	string
Rich Text	string
Number	number
Boolean	boolean
Date	string
Image	ImageField
Gallery	ImageField[]
Link	LinkField
Repeater	Array<any>
Select/Radio	string
Checkbox	boolean

Type-Safe Usage Example

After generating types, you get full autocomplete and type checking:

src/pages/index.astro

---
import { fetch } from '@aether-official/sites-sdk/astro';
import { SECTIONS, type HeroData } from '../aether-types';
import { getConfig } from '@aether-official/sites-sdk/astro';

const config = getConfig(import.meta.env);

// TypeScript knows this returns a Section with HeroData
const hero = await fetch.section(SECTIONS.HERO, config);
//    ^? const hero: Section<HeroData>

// Full autocomplete for fields!
const title = hero.data.title;
//                      ^? string

// TypeScript catches errors
const invalid = hero.data.doesNotExist;
//                        ^^^^^^^^^^^^^ Property does not exist
---

<section>
  <h1>{hero.data.title}</h1>
  <p>{hero.data.subtitle}</p>
</section>

Workflow

Initial Setup

# 1. Install SDK and CLI
npm install @aether-official/sites-sdk
npm install -D @aether-official/cli

# 2. Run interactive setup
npx aether-sdk init

# 3. Start developing with types!

After Schema Changes

When you add/modify templates in the visual editor:

# Fetch latest schema and regenerate types
npx aether-sdk sync
npx aether-sdk types

# Or run both together
npx aether-sdk sync && npx aether-sdk types

Your IDE will immediately have autocomplete for the new fields!

CI/CD Integration

Add to your build process to ensure types are always up-to-date:

{
  "scripts": {
    "prebuild": "aether-sdk sync && aether-sdk types",
    "build": "astro build"
  }
}

Troubleshooting

Connection Failed

Error: Connection failed: Unauthorized

Solutions:

• Verify your API token is correct
• Ensure the token hasn’t expired
• Check that your site is active

No Templates Found

Error: Found 0 section templates

Solutions:

• Create section templates in the visual editor first
• Verify you’re connecting to the correct site
• Check that templates aren’t deleted

Types Not Updating

Issue: Generated types don’t reflect recent changes

Solutions:

# Clear cache and regenerate
rm -rf .aether
npx aether-sdk sync && npx aether-sdk types

# Restart your dev server
npm run dev

Advanced Usage

Multiple Environments

Use different .env files for development and production:

.env.development

AETHER_SITE_ID=dev-site-id
AETHER_API_URL=http://localhost:3000

# .env.production
AETHER_SITE_ID=prod-site-id
AETHER_API_URL=https://cms.example.com

Load the appropriate config:

# Development
npx aether-sdk sync

# Production (with custom env file)
npx dotenv -e .env.production -- aether-sdk sync

Custom Output Paths

The CLI uses these default paths:

• Schema: .aether/schema.json
• Types: src/aether-types.d.ts

To customize, you can manually move the generated files or adjust your import paths.

Monorepo Setup

For monorepos, run the CLI from each package that needs types:

# Workspace structure
packages/
  website/          # Run CLI here
  marketing-site/   # And here
  docs/            # And here

# From root
cd packages/website && npx aether-sdk sync && npx aether-sdk types
cd packages/marketing-site && npx aether-sdk sync && npx aether-sdk types

Next Steps

• Content Fetching - Use generated types to fetch content
• API Reference - Complete SDK API documentation
• Visual Editor - Enable inline editing