@moltium/cli

CLI tool for creating and managing Moltium autonomous AI agents.

Installation

npm install -g @moltium/cli

Quick Start

# 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.

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.

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.

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

moltium migrate

Migrate between configuration types.

# 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.

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.

// 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.

# 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:

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):

# 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:

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

License

MIT