@circuitorg/agent-cli 1.0.1

package/README.md

@@ -0,0 +1,486 @@
+# Circuit CLI
+
+The official command-line tool for creating, testing, and deploying agents on the Circuit platform.
+
+## 📑 Table of Contents
+
+- [Circuit CLI](#circuit-cli)
+  - [📑 Table of Contents](#-table-of-contents)
+  - [🚀 Features](#-features)
+  - [📦 Installation](#-installation)
+    - [Installation Methods Explained](#installation-methods-explained)
+    - [For Private Repository Access](#for-private-repository-access)
+      - [Option 1: Direct Download (All Platforms)](#option-1-direct-download-all-platforms)
+      - [Option 2: Install via npm/Bun (Requires node/Bun Runtime)](#option-2-install-via-npmbun-requires-nodebun-runtime)
+    - [Installation Size Comparison](#installation-size-comparison)
+  - [🎯 Quick Start](#-quick-start)
+    - [First Steps](#first-steps)
+    - [Creating Your First Agent](#creating-your-first-agent)
+      - [Step 1a - From Scratch](#step-1a---from-scratch)
+      - [Step 1b - Adding an existing agent to the CLI agent registry](#step-1b---adding-an-existing-agent-to-the-cli-agent-registry)
+      - [Steps 2-5: Soft deploy, create session for testing, test locally, deploy live](#steps-2-5-soft-deploy-create-session-for-testing-test-locally-deploy-live)
+  - [📚 Command Reference](#-command-reference)
+    - [Core Commands](#core-commands)
+    - [Agent Commands](#agent-commands)
+    - [Simulation Commands](#simulation-commands)
+      - [Simulation Mode Flags](#simulation-mode-flags)
+    - [Authentication Commands](#authentication-commands)
+    - [Wallet Commands](#wallet-commands)
+  - [🔧 Configuration](#-configuration)
+    - [Project Configuration](#project-configuration)
+  - [🏗️ Agent Development](#️-agent-development)
+    - [Supported Project Types](#supported-project-types)
+      - [TypeScript Agents](#typescript-agents)
+      - [Python Agents](#python-agents)
+    - [Getting Started with Agents](#getting-started-with-agents)
+  - [🔧 Troubleshooting](#-troubleshooting)
+    - [Common Issues](#common-issues)
+      - ["No supported project type detected"](#no-supported-project-type-detected)
+      - ["Server failed to start within timeout"](#server-failed-to-start-within-timeout)
+      - ["Authentication Required"](#authentication-required)
+    - [Need Help?](#need-help)
+  - [📄 License](#-license)
+  - [📞 Support](#-support)
+  - [🔗 Related](#-related)
+
+## 🚀 Features
+
+- **Easy Setup**: Initialize new agents with a single command
+- **Local Testing**: Test your agents locally before deploying
+- **Interactive Mode**: User-friendly menus for all commands
+- **Multi-Language**: Support for both TypeScript and Python agents
+- **Zero Dependencies**: Standalone executables work out of the box
+- **Cross-Platform**: Works on macOS, Linux, and Windows
+
+## 📦 Installation
+
+### Installation Methods Explained
+
+**Two ways to install Circuit CLI:**
+
+1. **Standalone Executable (Recommended)** - No dependencies required
+   - What you get: A self-contained binary with embedded Bun runtime
+   - File size: ~57MB (includes everything needed)
+   - Best for: Python developers, CI/CD, users without Bun installed
+   - Works anywhere, no runtime dependencies
+
+2. **npm/Bun Package** - Requires Bun runtime
+   - What you get: Minified JavaScript bundle that runs with your local Bun
+   - File size: ~640KB (minified bundle)
+   - Best for: JavaScript/TypeScript developers who already have Bun
+   - Requires: Bun v1.0.0 or higher installed on your system
+
+### For Private Repository Access
+
+Since this repository is currently private, you'll need to download the executables directly from the GitHub releases page.
+
+#### Option 1: Direct Download (All Platforms)
+
+1. Go to the [releases page](https://github.com/circuitorg/agents-cli/releases/latest)
+2. Download the appropriate file for your platform:
+   - **macOS Intel**: `circuit-darwin-x64-vX.X.X.tar.gz`
+   - **macOS Apple Silicon**: `circuit-darwin-arm64-vX.X.X.tar.gz`
+   - **Linux x64**: `circuit-linux-x64-vX.X.X.tar.gz`
+   - **Linux ARM64**: `circuit-linux-arm64-vX.X.X.tar.gz`
+   - **Windows**: `circuit-windows-x64-vX.X.X.zip`
+
+3. Extract and install:
+```bash
+# macOS/Linux - One Liner after download
+cd ~/Downloads && tar -xzf circuit-darwin-arm64-v0.1.29.tar.gz && \
+sudo mv circuit-darwin-arm64 /usr/local/bin/circuit && \
+sudo xattr -rd com.apple.quarantine /usr/local/bin/circuit
+
+# Verify installation
+circuit --version
+```
+
+#### Option 2: Install via npm/Bun (Requires node/Bun Runtime)
+
+**⚠️ Prerequisites**: 
+- You must have Bun or node installed - bun install link: (`curl -fsSL https://bun.sh/install | bash`)
+- For global install, you must have a properly configured ~/.npmrc file
+```bash
+# Sample .npmrc file
+# Create a GitHub Personal Access Token with `read:packages` scope
+# https://github.com/settings/tokens/new
+@circuitorg:registry=https://npm.pkg.github.com
+//npm.pkg.github.com/:_authToken=${NPM_TOKEN}
+```
+
+```bash
+# Install the CLI (this installs TypeScript source, not a binary)
+npm install -g @circuitorg/agent-cli
+# or with Bun
+bun install -g @circuitorg/agent-cli
+```
+
+**Note**: This method installs a minified JavaScript bundle, not a compiled binary. The `circuit` command will run using your local Bun runtime.
+
+
+<!-- Remove this comment block when the repository becomes public -->
+<!--
+### For Public Repository (Future)
+### Option 1: Quick Install (Recommended)
+
+Download and install the standalone executable - no dependencies required:
+
+#### macOS/Linux (One-liner)
+```bash
+# Automatic detection of platform and architecture
+curl -fsSL https://raw.githubusercontent.com/circuitorg/agents-cli/main/install.sh | bash
+```
+
+#### macOS/Linux (Manual one-liner for specific platforms)
+```bash
+# macOS Apple Silicon
+curl -L https://github.com/circuitorg/agents-cli/releases/latest/download/circuit-darwin-arm64.tar.gz | tar -xz && sudo install -m 755 circuit-darwin-arm64 /usr/local/bin/circuit
+
+# macOS Intel
+curl -L https://github.com/circuitorg/agents-cli/releases/latest/download/circuit-darwin-x64.tar.gz | tar -xz && sudo install -m 755 circuit-darwin-x64 /usr/local/bin/circuit
+
+# Linux x64
+curl -L https://github.com/circuitorg/agents-cli/releases/latest/download/circuit-linux-x64.tar.gz | tar -xz && sudo install -m 755 circuit-linux-x64 /usr/local/bin/circuit
+```
+
+#### Windows
+```powershell
+# Quick install (PowerShell)
+Invoke-WebRequest -Uri "https://github.com/circuitorg/agents-cli/releases/latest/download/circuit-windows-x64.exe.zip" -OutFile "circuit.zip"
+Expand-Archive "circuit.zip" -Force
+Remove-Item "circuit.zip"
+# Add to PATH or move circuit.exe to a PATH directory
+```
+
+### Option 2: Install with package managers
+
+```bash
+# With Homebrew (macOS/Linux)
+brew install circuitorg/tap/circuit
+
+# With npm
+npm install -g @circuitorg/agent-cli
+
+# With Bun
+bun install -g @circuitorg/agent-cli
+```
+
+| Platform | Architecture | Download |
+|----------|--------------|----------|
+| macOS | Apple Silicon (M1/M2) | `circuit-darwin-arm64.tar.gz` |
+| macOS | Intel | `circuit-darwin-x64.tar.gz` |
+| Linux | x64 | `circuit-linux-x64.tar.gz` |
+| Linux | ARM64 | `circuit-linux-arm64.tar.gz` |
+| Windows | x64 | `circuit-windows-x64.exe.zip` |
+
+After downloading:
+```bash
+# macOS/Linux
+tar -xzf circuit-<platform>.tar.gz
+sudo mv circuit-<platform> /usr/local/bin/circuit
+chmod +x /usr/local/bin/circuit
+
+# Windows
+# Extract the zip and add to PATH
+```
+-->
+
+### Installation Size Comparison
+
+| Method | Download Size | Installed Size | Runtime Required |
+|--------|---------------|----------------|------------------|
+| Standalone Executable | ~20-25MB (compressed) | ~57MB | None (self-contained) |
+| npm/Bun Package | ~640KB | ~640KB | Bun v1.0.0+ |
+
+## 🎯 Quick Start
+
+### First Steps
+
+```bash
+# Verify installation
+circuit --version
+
+# See all available commands
+circuit --help
+
+# Start with interactive mode (recommended for beginners)
+circuit
+
+# Get a welcome overview and quick start guide
+circuit welcome
+```
+
+### Creating Your First Agent
+#### Step 1a - From Scratch
+
+```bash
+# (First time setup only) Authenticate your cli tool with your circuit account
+circuit auth login
+
+
+# Initialize a new agent project
+circuit agent init
+
+# Follow the prompts to:
+# - Choose TypeScript or Python
+# - Name your agent
+# - Set up the project structure
+
+# Navigate to your new agent
+cd my-agent
+
+# Install your local dependencies (required to run the 'circuit agent simulate' commands)
+bun install
+
+```
+
+#### Step 1b - Adding an existing agent to the CLI agent registry
+>Note: If you already have agents and want to deploy via the cli tool, you will need to go through the following steps to ensure the agent is aligned with the current deployment structure. 
+
+```bash
+# Navigate to your existing agent
+cd <existing-agent-dir>
+
+# Initialize the agent with --no-dir
+# This will add the agent to the CLI's agent registry, and add a main.py/pyproject.toml file (index.ts/package.json for TS agents) to your project.
+# If you already have a main.py file, it will create a main-RENAMEME.py file
+# If you already have a pyproject.toml file, it will simply add the correct circuit config section
+circuit agent init --no-dir
+
+# Install your local dependencies (required to run the 'circuit agent simulate' commands)
+bun install
+
+# Follow prompts to configure the agent
+```
+- Next you will need to copy over your existing execution and stop logic, place into the execute and stop functions defined in the template main.py file. See the sdk repo for more details on the overall structure of the app, but at a high level, you will simply need to define your execute and stop functions, and pass to the Agent class, which will handle exposing the correct endpoints based on its deployment location. 
+
+#### Steps 2-5: Soft deploy, create session for testing, test locally, deploy live
+```bash
+# Soft deploy your agent to register the agent with Circuit and allow the creation of a test session
+circuit agent deploy
+
+# Create a test session
+circuit agent sessions create
+
+# Test your agent locally
+circuit agent simulate execute
+
+# When ready, deploy to Circuit
+circuit agent deploy --live
+```
+
+
+## 📚 Command Reference
+
+### Core Commands
+
+| Command | Description |
+|---------|-------------|
+| `circuit` | Start interactive mode with menu |
+| `circuit --help` | Show help information |
+| `circuit --version` | Show version information |
+| `circuit info` | Display CLI information and status |
+| `circuit configure` | Configure CLI and agent settings |
+
+### Agent Commands
+
+| Command | Description |
+|---------|-------------|
+| `circuit agent` | Interactive agent management menu |
+| `circuit agent init` | Initialize a new agent project |
+| `circuit agent deploy` | Deploy an agent to Circuit platform |
+| `circuit agent configure` | Configure agent settings |
+| `circuit agent validate` | Validate agent configuration |
+| `circuit agent info` | Show agent information |
+| `circuit agent status` | Check agent deployment status |
+| `circuit agent sessions` | Manage agent sessions |
+| `circuit agent sessions create` | Create a new agent session |
+| `circuit agent sessions kill` | Kill an agent session |
+
+### Simulation Commands
+
+| Command | Description |
+|---------|-------------|
+| `circuit agent simulate` | Interactive simulation menu |
+| `circuit agent simulate execute` | Execute agent logic locally |
+| `circuit agent simulate stop` | Stop agent execution locally |
+
+#### Simulation Mode Flags
+
+You can bypass the interactive menu by specifying the simulation mode directly:
+
+| Flag | Description |
+|------|-------------|
+| `--local` or `-l` | Use local development mode (auto-start server) |
+| `--custom` or `-c` | Use custom server mode (connect to existing server) |
+| `--live` or `-L` | Use deployed/live version of the agent |
+| `--port <number>` or `-p <number>` | Specify port for custom server mode (default: prompts for input) |
+
+**Examples:**
+```bash
+# Test with local development server (auto-start)
+circuit agent simulate execute --local
+
+# Connect to custom server on port 8080
+circuit agent simulate execute --custom --port 8080
+
+# Test the deployed/live version
+circuit agent simulate execute --live
+
+# Stop simulation with custom server
+circuit agent simulate stop --custom --port 8080
+```
+
+### Authentication Commands
+
+| Command | Description |
+|---------|-------------|
+| `circuit auth` | Interactive authentication menu |
+| `circuit auth login` | Login to Circuit platform |
+| `circuit auth logout` | Logout from Circuit platform |
+| `circuit auth whoami` | Check current user |
+
+### Wallet Commands
+
+| Command | Description |
+|---------|-------------|
+| `circuit wallet` | Interactive wallet management menu |
+| `circuit wallet import` | Import a wallet |
+| `circuit wallet list` | List all wallets |
+
+
+
+## 🔧 Configuration
+
+### Project Configuration
+
+Create a `circuit.json` file in your agent project:
+
+```json
+{
+  "name": "my-agent",
+  "description": "My Circuit agent",
+  "environment": "development",
+  "projectType": "custom",
+  "runCommand": "bun index.ts",
+  "circuit": {
+    "name": "My Agent",
+    "slug": "my-agent",
+    "description": "A test agent",
+    "version": 1,
+    "defaultSleepIntervalMinutes": 15,
+    "imageUrl": "https://i.imgur.com/GCjt5Hs.png",
+    "allowedWalletTypes": ["ethereum"],
+    "filesToExclude": ["node_modules", ".git", "*.log"]
+  }
+}
+```
+
+## 🏗️ Agent Development
+
+### Supported Project Types
+
+The CLI supports two project types:
+
+#### TypeScript Agents
+
+```bash
+# Initialize TypeScript agent
+circuit agent init
+
+# Project structure:
+my-agent/
+├── index.ts          # Main agent file
+├── package.json      # Dependencies with @circuitorg/agents-sdk@0.1.4
+└── circuit.json      # Agent configuration
+```
+
+**Available Templates:**
+- **Bare**: Simple message sending template (recommended for beginners)
+- **More to come!**
+  
+#### Python Agents
+
+```bash
+# Initialize Python agent
+circuit agent init
+
+# Project structure:
+my-agent/
+├── main.py           # Main agent file
+├── pyproject.toml    # Dependencies
+└── circuit.json      # Agent configuration
+```
+
+### Getting Started with Agents
+
+When you run `circuit agent init`, the CLI will:
+
+1. Prompt you to choose TypeScript or Python
+2. For TypeScript: Select from available templates (bare, self-send, kitchen-sink-evm, or kitchen-sink-solana)
+3. Create a complete project structure with:
+   - Main agent file with example code
+   - Configuration file (`circuit.json`)
+   - Dependencies file (`package.json` or `pyproject.toml`)
+   - Ready-to-run agent template
+
+The generated agent includes:
+- HTTP server setup
+- Health check endpoint
+- Execute and stop functions
+- Proper error handling
+- Circuit SDK v1.0 integration with new unified API
+- Template-specific examples (balance checking, transfers, custom transactions)
+
+
+## 🔧 Troubleshooting
+
+### Common Issues
+
+#### "No supported project type detected"
+
+Make sure you're in a directory with the correct project structure:
+
+- **TypeScript**: `index.ts` + `package.json`
+- **Python**: `main.py` + `pyproject.toml`
+
+#### "Server failed to start within timeout"
+
+Check that your agent server:
+1. Has a `/health` endpoint
+2. Starts within the timeout period (default: 30 seconds)
+3. Binds to the correct port
+
+#### "Authentication Required"
+
+Run `circuit auth login` to authenticate with the Circuit platform.
+
+### Need Help?
+
+```bash
+# Show available commands
+circuit --help
+
+# Show help for specific command
+circuit agent --help
+
+# Enable verbose output
+circuit --verbose
+```
+
+## 📄 License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+
+## 📞 Support
+
+- **Documentation**: [GitHub Wiki](https://github.com/circuitorg/agents-cli/wiki)
+- **Issues**: [GitHub Issues](https://github.com/circuitorg/agents-cli/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/circuitorg/agents-cli/discussions)
+
+## 🔗 Related
+
+- [Circuit Platform](https://circuit.org)
+- [Circuit Agents SDK](https://github.com/circuitorg/agents-sdk)
+- [Bun Runtime](https://bun.sh)

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@circuitorg/agent-cli",
+  "version": "1.0.1",
+  "description": "A CLI tool for deploying agents to the Circuit platform",
+  "type": "module",
+  "bin": {
+    "circuit": "./circuit"
+  },
+  "files": [
+    "circuit",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "bun scripts/build.ts",
+    "dev": "bun --hot src/index.ts",
+    "test": "bun test",
+    "test:coverage": "bun test --coverage",
+    "typecheck": "bun tsc --noEmit",
+    "format": "bun x prettier --write src/**/*.ts",
+    "format:check": "bun x prettier --check src/**/*.ts",
+    "clean": "rm -f circuit circuit.exe circuit-*",
+    "all-checks": "bun run format:check && bun run typecheck && bun run test && bun run build && ./circuit --version"
+  },
+  "keywords": [
+    "cli",
+    "circuit",
+    "typescript",
+    "bun"
+  ],
+  "author": "circuitorg",
+  "license": "MIT",
+  "dependencies": {
+    "chalk": "^5.4.1",
+    "enquirer": "^2.4.1",
+    "minimatch": "^10.0.1",
+    "ora": "^8.2.0",
+    "terminal-link": "^4.0.0",
+    "tty-table": "^4.2.3",
+    "zod": "^4.0.5"
+  },
+  "devDependencies": {
+    "bun-types": "latest",
+    "prettier": "^3.0.0",
+    "typescript": "^5.3.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/circuitorg/agents-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/circuitorg/agents-cli/issues"
+  },
+  "homepage": "https://github.com/circuitorg/agents-cli#readme"
+}