@moltium/cli 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,273 @@
+# @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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moltium/cli",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "CLI tool for creating and managing Moltium autonomous agents",
   "license": "MIT",
   "keywords": [