@circuitorg/agent-cli 1.1.17 → 1.2.2

package/README.md

@@ -8,117 +8,57 @@ The official command-line tool for creating, testing, and publishing agents on t
   - [📑 Table of Contents](#-table-of-contents)
   - [🚀 Features](#-features)
   - [📦 Installation](#-installation)
-    - [Installation Methods Explained](#installation-methods-explained)
-      - [Option 1: Install via Bun (Requires Bun runtime)](#option-1-install-via-bun-requires-bun-runtime)
   - [🎯 Quick Start](#-quick-start)
-    - [First Steps](#first-steps)
-    - [Creating Your First Agent](#creating-your-first-agent)
   - [📚 Command Reference](#-command-reference)
     - [Core Commands](#core-commands)
-    - [Agent Management Commands](#agent-management-commands)
     - [Wallet Commands](#wallet-commands)
-    - [Run Command Flags](#run-command-flags)
+    - [Command Details](#command-details)
+      - [`circuit init`](#circuit-init)
+      - [`circuit run`](#circuit-run)
+      - [`circuit stop`](#circuit-stop)
     - [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)
   - [🔗 Related](#-related)
 
 ## 🚀 Features
 
-- **Easy Setup**: Initialize new agents with a single command
-- **Local Testing**: Test your agents locally before publishing
-- **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
+- Initialize new agents with a single command
+- Test agents locally before publishing
+- Support for TypeScript and Python
+- Cross-platform: macOS, Linux, and Windows
 
 ## 📦 Installation
 
-### Installation Methods Explained
-
-**How to install Circuit CLI:**
-
-1. **Bun package manager** - Requires Bun runtime
-2. **NPM package manager** - Coming soon
-
-
-#### Option 1: Install via Bun (Requires Bun runtime)
-
-**⚠️ Prerequisites**: 
-- You must have Bun or node installed - bun install link: (`curl -fsSL https://bun.sh/install | bash`)
+**Prerequisites**: Bun or Node.js installed ([Install Bun](https://bun.sh))
 
 ```bash
 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.
-
 
 ## 🎯 Quick Start
 
-### First Steps
-
-```bash
-# Verify installation
-circuit --version
-
-# RECOMMENDED FIRST STEP: Get an overview of the tooling and quick start guide
-circuit help
-```
-
-### Creating Your First Agent
-
-**Streamlined Workflow:**
-
 ```bash
-# 1. Authenticate your cli tool with your circuit account
+# Authenticate
 circuit login
 
-# 2. Initialize a new agent project (optionally pass --no-dir to use an existing folder)
+# Create a new agent
 circuit init
-# Follow the prompts to:
-# - Choose TypeScript or Python
-# - Name your agent
-# - Set up the project structure
 
-# 3. Navigate to your new agent (Skip if you passed --no-dir above)
-cd <generated-folder>
+# Navigate to agent directory
+cd <agent-name>
 
-# 4. Install dependencies
-bun install    # For TypeScript agents
-# OR
-uv sync       # For Python agents
+# Install dependencies
+bun install    # TypeScript
+uv sync        # Python
 
-# 5. Test your agent (handles setup, session creation automatically)
+# Test locally
 circuit run
 
-# 6. Publish to production when ready
+# Publish to production
 circuit publish
 ```
 
-**Existing Agent Setup:**
-
-```bash
-# Navigate to your existing agent directory
-cd <existing-agent-dir>
-
-# Initialize with --no-dir to configure existing project
-circuit init --no-dir
-# This adds the agent to CLI registry and updates config files
-
-# Install dependencies
-bun install  # or uv sync for Python
-
-# Test your agent
-circuit run
-```
-
-> **Note**: For existing agents, copy your execution logic into the execute/stop functions in the generated template files. See the SDK documentation for details on the Agent class structure.
-
 
 ## 📚 Command Reference
 
@@ -130,16 +70,11 @@ circuit run
 | `circuit login` | Authenticate with Circuit platform |
 | `circuit logout` | Sign out from Circuit platform |
 | `circuit init` | Initialize a new agent project |
-| `circuit run` | Run/test your agent (handles setup automatically) |
+| `circuit run` | Test your agent locally |
+| `circuit stop` | Stop a running agent session |
 | `circuit publish` | Publish agent to production |
 | `circuit help` | Show detailed help and getting started guide |
-
-### Agent Management Commands
-
-| Command | Description |
-|---------|-------------|
-| `circuit agent info` | Show current agent information |
-| `circuit agent status` | Check agent ment status |
+| `circuit info` | Display CLI and current agent information |
 
 ### Wallet Commands
 
@@ -148,88 +83,54 @@ circuit run
 | `circuit wallet list` | List your available wallets |
 | `circuit wallet import` | Import a new wallet for testing |
 
-### Run Command Flags
+### Command Details
+
+#### `circuit init`
+Creates a new agent project:
+- Prompts for language (TypeScript or Python) and agent name
+- Generates project structure with `.circuit.toml` config file
+
+Each agent stores its configuration in a local `.circuit.toml` file.
 
-The `circuit run` command supports these optional flags to skip interactive prompts:
+#### `circuit run`
+Runs your un-published agent code:
+- Creates a session if needed
+- Starts local agent server
+- Executes your agent's run command
 
-| Flag | Description |
-|------|-------------|
-| `--wallet <address>` | Use specific wallet address |
-| `--mode local\|live\|custom` | Set simulation mode |
-| `--action execute\|stop` | Choose action to perform |
-| `--port <number>` | Port for custom server mode |
+**Flags:**
+- `--wallet <address>` or `-w <address>` - Specify wallet address
 
-**Examples:**
 ```bash
-# Interactive mode (recommended)
 circuit run
+circuit run --wallet 0x123...
+```
 
-# Skip prompts with flags
-circuit run --wallet 0x123... --mode local --action execute
+#### `circuit stop`
+Stops a running agent session and cleans up resources.
 
-# Connect to custom server
-circuit run --mode custom --port 8080
+**Flags:**
+- `--wallet <address>` or `-w <address>` - Specify wallet address
 
-# Stop simulation with custom server
-circuit run --mode custom --port 8080 --action stop
+```bash
+circuit stop
+circuit stop --wallet 0x123...
 ```
 
 ### Getting Started with Agents
 
-When you run `circuit init`, the CLI will:
-
-1. Prompt you to choose TypeScript or Python
-2. For TypeScript: Select from available templates (bare, self-send)
-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
+`circuit init` generates:
+- Main agent file: `index.ts` (TypeScript) or `main.py` (Python)
+- Configuration: `.circuit.toml`
+- Dependencies: `package.json` or `pyproject.toml`
 
-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)
+Your agent code implements two commands:
+- `run` - Executes your agent logic
+- `stop` - Handles cleanup when stopping
 
 
 ## 🔧 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 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
-```
-
+**User feedback and common questions will be populated here as it comes in**
 ## 🔗 Related
 
 - [Circuit Agents SDK Typescript](https://www.npmjs.com/package/@circuitorg/agent-sdk)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@circuitorg/agent-cli",
-  "version": "1.1.17",
+  "version": "1.2.2",
   "description": "A CLI tool for publishing agents to the Circuit platform",
   "type": "module",
   "bin": {