@plosson/agentio 0.1.27 → 0.1.28

package/README.md

@@ -1,8 +1,55 @@
 # agentio
 
-CLI for LLM agents to interact with communication and tracking services.
+**Run LLM agent workflows in GitHub Actions. No servers. No Zapier. Just cron.**
+
+agentio is a CLI that lets LLM agents interact with Gmail, Slack, JIRA, Telegram, Google Chat, and RSS feeds. Designed for CI/CD pipelines and scheduled automation.
+
+## Why agentio?
+
+You want your AI agent to:
+- Send a daily Slack summary of unread emails
+- Monitor RSS feeds and post to Telegram
+- Update JIRA tickets based on email threads
+- Run on a schedule, without managing servers
+
+**agentio makes this trivial.** Authenticate once locally, export your config as a single encrypted file, and run anywhere — GitHub Actions, GitLab CI, or any CI/CD platform.
+
+## Quick Example
+
+A scheduled workflow that reads your emails, has Claude summarize them, and posts to Slack:
+
+```yaml
+# .github/workflows/daily-briefing.yml
+name: Daily Briefing
+on:
+  schedule:
+    - cron: '0 7 * * 1-5'
+
+jobs:
+  briefing:
+    runs-on: ubuntu-latest
+    env:
+      AGENTIO_CONFIG: ${{ secrets.AGENTIO_CONFIG }}
+      AGENTIO_KEY: ${{ secrets.AGENTIO_KEY }}
+      CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+    steps:
+      - uses: actions/checkout@v4
+      - run: curl -LsSf https://agentio.work/install | sh
+      - run: npm install -g @anthropic-ai/claude-code
+      - run: agentio config import && agentio claude install
+      - run: claude -p "$(cat prompt.md)" --max-turns 30 --dangerously-skip-permissions
+```
+
+```markdown
+# prompt.md
+Fetch my unread emails from the last 24 hours using agentio-gmail.
+Summarize them by urgency and sender.
+Post the summary to Slack using agentio-slack.
+```
 
-## Quick Install
+See [`examples/daily-briefing/`](./examples/daily-briefing) for the complete working example.
+
+## Install
 
 **macOS / Linux:**
 ```bash
@@ -14,150 +61,154 @@ curl -LsSf https://agentio.work/install | sh
 iwr -useb https://agentio.work/install.ps1 | iex
 ```
 
-## Update
-
-```bash
-agentio update
-```
-
-## Alternative Installation Methods
-
 <details>
-<summary>Homebrew (macOS/Linux)</summary>
+<summary><strong>Other methods</strong> (Homebrew, Scoop, npm)</summary>
 
+**Homebrew (macOS/Linux):**
 ```bash
 brew tap plosson/agentio
 brew install agentio
 ```
-</details>
-
-<details>
-<summary>Scoop (Windows)</summary>
 
+**Scoop (Windows):**
 ```powershell
 scoop bucket add agentio https://github.com/plosson/scoop-agentio
 scoop install agentio
 ```
-</details>
-
-<details>
-<summary>npm / bun</summary>
 
+**npm / bun:**
 ```bash
-# Run directly
-bunx @plosson/agentio --help
 npx @plosson/agentio --help
-
-# Global install
-bun add -g @plosson/agentio
+# or global install
 npm install -g @plosson/agentio
 ```
+
 </details>
 
-<details>
-<summary>Direct binary download</summary>
+## Setup: Authenticate Once, Run Anywhere
 
-Download from [GitHub Releases](https://github.com/plosson/agentio/releases/latest):
-- macOS: `agentio-darwin-arm64` (Apple Silicon) or `agentio-darwin-x64` (Intel)
-- Linux: `agentio-linux-x64` or `agentio-linux-arm64`
-- Windows: `agentio-windows-x64.exe`
-</details>
+### 1. Authenticate locally
 
-## Services
+```bash
+# Add your Gmail account (opens browser for OAuth)
+agentio gmail profile add
 
-| Service | Status | Commands |
-|---------|--------|----------|
-| Gmail | Available | `list`, `get`, `search`, `send`, `reply`, `archive`, `mark`, `attachment`, `export` |
-| Telegram | Available | `send` |
-| Google Chat | Available | `send`, `list`, `get` |
-| Slack | Available | `send` |
-| JIRA | Available | `projects`, `search`, `get`, `comment`, `transitions`, `transition` |
-| RSS | Available | `articles`, `get`, `info` |
-| Linear | Planned | - |
+# Add Slack webhook
+agentio slack profile add
 
-## Usage
+# Add any other services you need...
+```
 
-### Gmail
+### 2. Export your config
 
 ```bash
-# First, authenticate
-agentio gmail profile add
+agentio config export
+# Outputs:
+#   ✓ Exported to agentio.config
+#   ✓ Encryption key: abc123...
+#
+# Store BOTH in your CI/CD secrets!
+```
 
-# List recent emails
-agentio gmail list --limit 10
+All credentials are encrypted with AES-256-GCM. The export file is useless without the key.
 
-# Search emails
-agentio gmail search --query "from:boss@company.com is:unread"
+**Note:** GitHub secrets are limited to 48KB per secret. Only add the profiles you need for your workflow to keep the exported config small.
 
-# Get a specific email
-agentio gmail get <message-id>
+### 3. Add to GitHub Secrets
+
+| Secret | Value |
+|--------|-------|
+| `AGENTIO_CONFIG` | Base64-encoded contents of `agentio.config` |
+| `AGENTIO_KEY` | The encryption key from export |
 
-# Send an email
-agentio gmail send --to user@example.com --subject "Hello" --body "Message body"
+```bash
+# Get base64 for GitHub secret
+cat agentio.config | base64
+```
 
-# Or pipe content
-echo "Message body" | agentio gmail send --to user@example.com --subject "Hello"
+### 4. Use in your workflow
 
-# Download attachments
-agentio gmail attachment <message-id>
-agentio gmail attachment <message-id> --name "document.pdf" --output ./downloads
+```yaml
+env:
+  AGENTIO_CONFIG: ${{ secrets.AGENTIO_CONFIG }}
+  AGENTIO_KEY: ${{ secrets.AGENTIO_KEY }}
 
-# Export email as PDF
-agentio gmail export <message-id>
-agentio gmail export <message-id> --output email.pdf
+steps:
+  - run: agentio config import  # Auto-detects env vars
+  - run: agentio gmail list --limit 10
 ```
 
-### Telegram
+Done. Your agent can now access all your services securely in CI/CD.
 
-```bash
-# Set up bot profile (interactive wizard)
-agentio telegram profile add
+## Services
 
-# Send message to channel
-agentio telegram send "Hello from agentio!"
+| Service | Auth | Commands |
+|---------|------|----------|
+| **Gmail** | OAuth | `list`, `get`, `search`, `send`, `reply`, `archive`, `mark`, `attachment`, `export` |
+| **Slack** | Webhook | `send` |
+| **Telegram** | Bot Token | `send` |
+| **Google Chat** | Webhook/OAuth | `send`, `list`, `get` |
+| **JIRA** | OAuth | `projects`, `search`, `get`, `comment`, `transitions`, `transition` |
+| **Discourse** | API Key | `list`, `get`, `categories` |
+| **RSS** | None | `articles`, `get`, `info` |
 
-# Send with formatting
-agentio telegram send --parse-mode markdown "**Bold** and _italic_"
-```
+## Usage Examples
 
-### Google Chat
+<details>
+<summary><strong>Gmail</strong></summary>
 
 ```bash
-# Set up profile (webhook or OAuth)
-agentio gchat profile add
+# List recent emails
+agentio gmail list --limit 10
 
-# Send message via webhook
-agentio gchat send "Hello from agentio!"
+# Search
+agentio gmail search --query "from:boss@company.com is:unread"
 
-# Send with JSON payload for rich messages
-agentio gchat send --json message.json
+# Get specific email
+agentio gmail get <message-id>
 
-# List messages (OAuth profiles only)
-agentio gchat list --space <space-id>
+# Send (body from stdin works great with LLMs)
+echo "Generated by my agent" | agentio gmail send --to user@example.com --subject "Daily Report"
+
+# Download attachments
+agentio gmail attachment <message-id> --output ./downloads
 
-# Get a specific message (OAuth profiles only)
-agentio gchat get <message-id> --space <space-id>
+# Export as PDF
+agentio gmail export <message-id> --output email.pdf
 ```
 
-### Slack
+</details>
 
-```bash
-# Set up webhook profile
-agentio slack profile add
+<details>
+<summary><strong>Slack</strong></summary>
 
+```bash
 # Send message
-agentio slack send "Hello from agentio!"
+agentio slack send "Deployment complete ✓"
 
-# Send Block Kit message from JSON file
+# Send rich Block Kit message
 agentio slack send --json blocks.json
 ```
 
-### JIRA
+</details>
+
+<details>
+<summary><strong>Telegram</strong></summary>
 
 ```bash
-# Authenticate with OAuth
-agentio jira profile add
+# Send to channel
+agentio telegram send "Alert: New items found"
+
+# With markdown
+agentio telegram send --parse-mode markdown "**Bold** and _italic_"
+```
 
+</details>
+
+<details>
+<summary><strong>JIRA</strong></summary>
+
+```bash
 # List projects
 agentio jira projects
 
@@ -168,39 +219,38 @@ agentio jira search --jql "assignee = currentUser() AND status != Done"
 # Get issue details
 agentio jira get PROJ-123
 
-# Add a comment
-agentio jira comment PROJ-123 "This is my comment"
-
-# View available transitions
-agentio jira transitions PROJ-123
+# Add comment
+agentio jira comment PROJ-123 "Automated update from CI"
 
-# Transition an issue
+# Transition issue
+agentio jira transitions PROJ-123  # see available transitions
 agentio jira transition PROJ-123 <transition-id>
 ```
 
-### RSS
+</details>
+
+<details>
+<summary><strong>RSS</strong></summary>
 
 ```bash
-# List articles from a blog (feed URL auto-discovered)
-agentio rss articles https://simonwillison.net
-agentio rss articles https://steipete.me --limit 5
+# List articles (auto-discovers feed URL)
+agentio rss articles https://simonwillison.net --limit 10
 
 # Filter by date
-agentio rss articles https://blog.fsck.com --since 2025-01-01
+agentio rss articles https://blog.example.com --since 2025-01-01
 
-# Get feed info (shows discovered feed URL)
-agentio rss info https://kau.sh
-
-# Get a specific article
+# Get full article
 agentio rss get https://simonwillison.net <article-url>
 ```
 
+</details>
+
 ## Multi-Profile Support
 
-Each service supports multiple named profiles:
+Manage multiple accounts per service:
 
 ```bash
-# Add profiles for different accounts
+# Add named profiles
 agentio gmail profile add --profile work
 agentio gmail profile add --profile personal
 
@@ -208,90 +258,71 @@ agentio gmail profile add --profile personal
 agentio gmail list --profile work
 ```
 
-## Claude Code Integration
-
-agentio provides plugins for [Claude Code](https://claude.ai/download) with skills for Gmail, Telegram, Google Chat, JIRA, and RSS operations.
-
-### Install Marketplaces and Plugins
-
-```bash
-# Add a marketplace (auto-detected from URL)
-agentio claude install https://github.com/plosson/agentio
-
-# Install a plugin (auto-detected from name@marketplace format)
-agentio claude install agentio-gmail@agentio
-
-# Install all from agentio.json
-agentio claude install
+## Workflow Examples
+
+The [`examples/`](./examples) folder contains ready-to-use workflows. Here's how it works:
+
+### Daily Email Briefing → Slack
+
+```yaml
+name: Daily Briefing
+on:
+  schedule:
+    - cron: '0 7 * * 1-5'  # Weekdays at 7 AM UTC
+
+jobs:
+  briefing:
+    runs-on: ubuntu-latest
+    env:
+      AGENTIO_CONFIG: ${{ secrets.AGENTIO_CONFIG }}
+      AGENTIO_KEY: ${{ secrets.AGENTIO_KEY }}
+      CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+    steps:
+      - uses: actions/checkout@v4
+      - run: curl -LsSf https://agentio.work/install | sh
+      - run: npm install -g @anthropic-ai/claude-code
+      - run: agentio config import && agentio claude install
+      - run: claude -p "$(cat prompt.md)" --max-turns 30 --dangerously-skip-permissions
 ```
 
-### Manage Plugins
-
-```bash
-# List marketplaces and plugins from agentio.json
-agentio claude list
+The magic is in `prompt.md` — Claude reads your emails via the agentio plugin, analyzes them, and posts a summary to Slack:
 
-# Update marketplaces
-agentio claude update
-agentio claude update https://github.com/plosson/agentio
+```markdown
+# Daily Email Briefing
 
-# Remove a marketplace or plugin
-agentio claude remove https://github.com/plosson/agentio
-agentio claude remove agentio-gmail@agentio
+1. Fetch unread emails from the last 24 hours using agentio-gmail
+2. Categorize by urgency: Urgent / Important / FYI
+3. Generate a morning briefing with one-line summaries
+4. Send to Slack using agentio-slack
 ```
 
-### agentio.json
-
-Projects can define marketplaces and plugins in an `agentio.json` file:
+See [`examples/daily-briefing/`](./examples/daily-briefing) for the complete working example.
 
-```json
-{
-  "marketplaces": [
-    "https://github.com/plosson/agentio"
-  ],
-  "plugins": [
-    "agentio-gmail@agentio",
-    "agentio-rss@agentio"
-  ]
-}
-```
-
-## Design
-
-agentio is designed for LLM consumption:
-
-- **Structured output**: Human-readable text output optimized for LLM parsing
-- **Clear errors**: Error messages written to stderr with suggestions
-- **Stdin support**: Pipe content to commands that accept body text
-- **Multi-profile**: Manage multiple accounts per service
-
-## Configuration
-
-Configuration is stored in `~/.config/agentio/`:
-
-- `config.json` - Profile names and defaults
-- `tokens.enc` - Encrypted credentials (AES-256-GCM)
+## Claude Code Integration
 
-### Export/Import
+agentio includes skills for [Claude Code](https://claude.ai/download) that let Claude directly read your email, post to Slack, or query JIRA during conversations.
 
-Transfer configuration between machines:
+**Install skills:**
 
 ```bash
-# Export configuration (generates encryption key)
-agentio config export
+agentio claude install https://github.com/plosson/agentio  # marketplace
+agentio claude install agentio-gmail@agentio               # Gmail skill
+agentio claude install agentio-jira@agentio                # JIRA skill
+```
 
-# Export with custom output file
-agentio config export --output backup.config
+**Then in Claude Code:**
 
-# Import on another machine
-agentio config import agentio.config --key <encryption-key>
+> "Summarize my unread emails and post a summary to Slack"
 
-# Or use environment variable
-AGENTIO_KEY=<key> agentio config import agentio.config
+Claude uses the installed skills to fetch emails and send the summary — no manual commands needed.
 
-# Merge with existing config instead of replacing
-agentio config import agentio.config --key <key> --merge
-```
+## Design Principles
+
+- **Structured output** — Text output optimized for LLM parsing
+- **Stdin support** — Pipe content to commands (`echo "msg" | agentio slack send`)
+- **Single config export** — One encrypted file + key = full portability
+- **Multi-profile** — Multiple accounts per service
+- **No runtime dependencies** — Single binary, runs anywhere
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plosson/agentio",
-  "version": "0.1.27",
+  "version": "0.1.28",
   "description": "CLI for LLM agents to interact with communication and tracking services",
   "type": "module",
   "license": "MIT",

package/src/auth/jira-oauth.ts

@@ -9,11 +9,11 @@ const ATLASSIAN_RESOURCES_URL = 'https://api.atlassian.com/oauth/token/accessibl
 const JIRA_SCOPES = [
   'read:jira-work',   // Read projects, issues
   'write:jira-work',  // Add comments, change status
+  'read:me',          // Read current user info
   'offline_access',   // Get refresh tokens
 ];
 
-const PORT_RANGE_START = 3000;
-const PORT_RANGE_END = 3010;
+const OAUTH_PORT = 9999;
 
 export interface JiraOAuthResult {
   accessToken: string;
@@ -31,23 +31,6 @@ export interface AtlassianSite {
   avatarUrl?: string;
 }
 
-async function findAvailablePort(): Promise<number> {
-  for (let port = PORT_RANGE_START; port <= PORT_RANGE_END; port++) {
-    try {
-      await new Promise<void>((resolve, reject) => {
-        const server = createServer();
-        server.listen(port, () => {
-          server.close(() => resolve());
-        });
-        server.on('error', reject);
-      });
-      return port;
-    } catch {
-      continue;
-    }
-  }
-  throw new Error(`No available port found in range ${PORT_RANGE_START}-${PORT_RANGE_END}`);
-}
 
 async function exchangeCodeForTokens(
   code: string,
@@ -130,8 +113,7 @@ export async function refreshJiraToken(
 export async function performJiraOAuthFlow(
   selectSite?: (sites: AtlassianSite[]) => Promise<AtlassianSite>
 ): Promise<JiraOAuthResult> {
-  const port = await findAvailablePort();
-  const redirectUri = `http://localhost:${port}/callback`;
+  const redirectUri = `http://localhost:${OAUTH_PORT}/callback`;
 
   const state = Math.random().toString(36).substring(2);
   const authUrl = new URL(ATLASSIAN_AUTH_URL);
@@ -152,7 +134,7 @@ export async function performJiraOAuthFlow(
     }, 5 * 60 * 1000);
 
     server = createServer(async (req, res) => {
-      const url = new URL(req.url || '', `http://localhost:${port}`);
+      const url = new URL(req.url || '', `http://localhost:${OAUTH_PORT}`);
 
       if (url.pathname !== '/callback') {
         res.writeHead(404);
@@ -230,7 +212,7 @@ export async function performJiraOAuthFlow(
       }
     });
 
-    server.listen(port, () => {
+    server.listen(OAUTH_PORT, () => {
       console.error(`\nOpening browser for Atlassian authorization...`);
       console.error(`If browser doesn't open, visit:\n${authUrl.toString()}\n`);
 

package/src/commands/config.ts

@@ -112,8 +112,8 @@ export function registerConfigCommands(program: Command): void {
 
   config
     .command('import')
-    .description('Import configuration and credentials from an encrypted file')
-    .argument('<file>', 'Path to the encrypted configuration file')
+    .description('Import configuration and credentials from an encrypted file or environment variables')
+    .argument('[file]', 'Path to the encrypted configuration file (optional if AGENTIO_CONFIG env var is set)')
     .option('--key <key>', 'Encryption key (64 hex characters). Falls back to AGENTIO_KEY env var')
     .option('--merge', 'Merge with existing configuration instead of replacing')
     .action(async (file, options) => {
@@ -137,26 +137,47 @@ export function registerConfigCommands(program: Command): void {
           );
         }
 
-        // Check file exists
-        const filePath = file.startsWith('/') ? file : join(process.cwd(), file);
-        if (!existsSync(filePath)) {
+        let encryptedContent: string;
+
+        if (file) {
+          // Read from file
+          const filePath = file.startsWith('/') ? file : join(process.cwd(), file);
+          if (!existsSync(filePath)) {
+            throw new CliError(
+              'NOT_FOUND',
+              `File not found: ${filePath}`,
+              'Provide a valid path to the exported configuration file'
+            );
+          }
+          encryptedContent = await readFile(filePath, 'utf-8');
+        } else if (process.env.AGENTIO_CONFIG) {
+          // Decode from AGENTIO_CONFIG environment variable (base64-encoded)
+          try {
+            encryptedContent = Buffer.from(process.env.AGENTIO_CONFIG, 'base64').toString('utf-8');
+          } catch {
+            throw new CliError(
+              'INVALID_PARAMS',
+              'Failed to decode AGENTIO_CONFIG',
+              'AGENTIO_CONFIG must be a valid base64-encoded string'
+            );
+          }
+        } else {
           throw new CliError(
-            'NOT_FOUND',
-            `File not found: ${filePath}`,
-            'Provide a valid path to the exported configuration file'
+            'INVALID_PARAMS',
+            'No configuration source provided',
+            'Provide a file path or set AGENTIO_CONFIG environment variable (base64-encoded)'
           );
         }
 
-        // Read and parse the encrypted file
-        const encryptedContent = await readFile(filePath, 'utf-8');
+        // Parse the encrypted content
         let encrypted: { iv: string; tag: string; data: string };
         try {
           encrypted = JSON.parse(encryptedContent);
         } catch {
           throw new CliError(
             'INVALID_PARAMS',
-            'Invalid file format',
-            'The file does not appear to be a valid agentio export file'
+            'Invalid configuration format',
+            'The configuration does not appear to be a valid agentio export'
           );
         }