npm package: @moltium/cli
Description: CLI tool for creating and managing Moltium autonomous agents
Latest version: 0.1.34

# @moltium/cli

CLI tool for creating and managing Moltium autonomous AI agents.

## Installation

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

## Quick Start

```bash
# Scaffold a new agent (interactive prompts)
moltium init my-agent

# Enter the project directory
cd my-agent

# Install dependencies
npm install

# Add your API keys to .env
# Edit .env with your ANTHROPIC_API_KEY or OPENAI_API_KEY

# Start the agent
npm start
```

## Commands

### `moltium init [name]`

Scaffold a new agent project with interactive prompts.

**Prompts:**
- **Agent name** — directory name and config identifier
- **Agent type** — free text (e.g. `assistant`, `trader`, `moderator`)
- **Configuration type** — `code` (TypeScript) or `markdown` (natural language)
- **LLM provider** — Anthropic (Claude) or OpenAI (GPT)
- **Social platforms** — Moltbook, Twitter, both, or none
- **Deployment target** — Railway, Render, AWS, DigitalOcean, Custom, or None

**Code-based output:**
```
my-agent/
  start.ts               # Agent entry point
  agent.config.ts        # Main configuration (TypeScript)
  actions/example.ts     # Starter custom action
  hooks/onInit.ts        # Initialization hook
  hooks/onTick.ts        # Autonomous loop hook
  hooks/onShutdown.ts    # Graceful shutdown hook
  package.json
  tsconfig.json
  .env
```

**Markdown-based output:**
```
my-agent/
  start.ts               # Agent entry point
  agent.md               # Main configuration (Markdown)
  skills/                # Skill definitions (.md files)
  personality/           # Bio and trait definitions
  prompts/system.md      # System prompt template
  memory/context.md      # Long-term context
  package.json
  .env
```

### `moltium start`

Start the agent locally from the current directory.

```bash
moltium start                  # Default port 3000
moltium start --port 8080      # Custom port
moltium start --debug          # Enable debug logging
moltium start --env .env.local # Custom env file
```

The start command auto-detects whether you're using code-based or markdown-based configuration, loads all hooks/skills/personality files, and starts the Express server.

### `moltium deploy [platform]`

Deploy your agent to a cloud platform.

```bash
moltium deploy railway       # Deploy to Railway
moltium deploy render        # Deploy to Render
moltium deploy aws           # Deploy to AWS (ECS/Fargate)
moltium deploy digitalocean  # Deploy to DigitalOcean App Platform
moltium deploy custom        # Deploy using custom config
```

Each platform has prerequisites (CLI tools, API keys). Run `moltium deploy` without arguments to see all available platforms.

Deployment configuration is read from `deployment.config.ts` in your project directory. This file is generated during `moltium init` if you select a deployment target.

### `moltium config show`

Display the current agent configuration.

```bash
moltium config show       # Show parsed config
moltium config validate   # Validate config without starting
```

### `moltium migrate`

Migrate between configuration types.

```bash
# Convert code config to markdown
moltium migrate --from code --to markdown

# Convert markdown config to code
moltium migrate --from markdown --to code

# Keep the original file (don't rename to .bak)
moltium migrate --from code --to markdown --keep
```

Migration preserves your agent's name, personality, social settings, behaviors, and memory config. Code-to-markdown generates skill files from your actions. Markdown-to-code generates hook stubs and a TypeScript config.

### `moltium status`

Check if your agent is running.

```bash
moltium status                       # Check localhost:3000
moltium status --port 8080           # Check custom port
moltium status --remote https://my-agent.up.railway.app  # Check remote
```

## Configuration Types

### Code-Based (TypeScript)

For developers who want full type safety and maximum flexibility.

```typescript
// agent.config.ts
import type { AgentConfig } from '@moltium/core';
import { myCustomAction } from './actions/my-action.js';

export default {
  name: 'my-agent',
  type: 'assistant',
  personality: {
    traits: ['helpful', 'curious'],
    bio: 'A helpful autonomous agent.',
  },
  llm: {
    provider: 'anthropic',
    model: 'claude-sonnet-4-20250514',
    apiKey: process.env.ANTHROPIC_API_KEY!,
  },
  social: {},
  behaviors: {
    autonomous: true,
    decisionMaking: 'llm-driven',
    actionsPerHour: 5,
  },
  memory: { type: 'memory' },
  actions: ['post_social_update'],
  customActions: [myCustomAction],
} satisfies AgentConfig;
```

### Markdown-Based (Natural Language)

For non-developers who prefer simple, readable configuration.

```markdown
# Agent Configuration

## Identity
name: my-agent
type: assistant
personality: helpful, curious

## Bio
A helpful autonomous agent that assists with daily tasks.

## Behaviors
autonomous: true
decision_making: llm-driven
actions_per_hour: 5

## Skills

### Respond to Messages
Handle incoming messages with helpful, concise responses.

### Post Updates
Share useful tips and insights with the community.

## Memory
type: memory
retention: 30 days
```

Skills in markdown are interpreted by the LLM at runtime — no code required.

## Deployment Targets

| Platform | Method | Prerequisites |
|----------|--------|---------------|
| Railway | CLI | `npm i -g @railway/cli` + `railway login` |
| Render | REST API | `RENDER_API_KEY` in `.env` |
| AWS | ECS/Fargate | AWS CLI configured (`aws configure`) |
| DigitalOcean | App Platform API | `DO_API_TOKEN` in `.env` |
| Custom | Docker/SSH/CLI/API | Varies by method |

### Custom Deployment

The custom deployer supports four methods. Configure in `deployment.config.ts`:

```typescript
import type { DeploymentConfig } from '@moltium/core';

export default {
  platform: 'custom',
  customConfig: {
    deploymentMethod: 'docker', // 'docker' | 'ssh' | 'cli' | 'api'
    buildCommand: 'npm run build',
    startCommand: 'npm start',
    docker: {
      registry: 'docker.io',
      imageName: 'my-agent',
      hostUrl: 'localhost',
      containerPort: 3000,
      hostPort: 80,
    },
  },
} satisfies DeploymentConfig;
```

## Environment Variables

Your `.env` file (generated by `moltium init`):

```bash
# LLM (at least one required)
ANTHROPIC_API_KEY=your-api-key-here
OPENAI_API_KEY=your-api-key-here

# Social (per enabled platform)
MOLTBOOK_API_KEY=your-moltbook-key
TWITTER_API_KEY=your-twitter-api-key
TWITTER_API_SECRET=your-twitter-api-secret
TWITTER_ACCESS_TOKEN=your-twitter-access-token
TWITTER_ACCESS_SECRET=your-twitter-access-secret

# Server
PORT=3000
LOG_LEVEL=info
```

## Running Without Global Install

You can also use `npx`:

```bash
npx @moltium/cli init my-agent
npx @moltium/cli start
npx @moltium/cli deploy railway
```

## License

MIT