supyagent 0.6.3

Cloud CLI for supyagent — connect AI agents to third-party services

Supyagent

Give your AI agents 50+ cloud tools — Gmail, Slack, GitHub, Calendar, Drive, and more — with one CLI.

Get Started in 60 Seconds

# 1. Install
pip install supyagent

# 2. Connect your accounts (opens browser to authorize)
supyagent connect

# 3. Run a tool
supyagent service run gmail_list_messages '{"maxResults": 5}'

That's it. You just read your Gmail from the command line.

---

What Is Supyagent?

Supyagent connects AI agents and developer tools to third-party services through a unified CLI. You authenticate once on the dashboard, connect your integrations (Google, Slack, GitHub, etc.), and then call any tool from the terminal or from your agent framework.

Supported services: Gmail, Google Calendar, Google Drive, Google Slides, Google Sheets, Google Docs, Slack, GitHub, Discord, Notion, Microsoft 365 (Outlook, Calendar, OneDrive), Twitter/X, LinkedIn, HubSpot, Telegram, WhatsApp, Calendly, Linear, Pipedrive, Resend, and more.

CLI Reference

Command	Description
supyagent connect	Authenticate with the service (device auth flow)
supyagent disconnect	Remove stored credentials
supyagent status	Show connection status and available tools
supyagent service tools	List all available cloud tools
supyagent service run <tool> '<json>'	Execute a cloud tool
supyagent inbox	View and manage incoming webhook events
supyagent skills generate	Generate skill files for AI coding assistants
supyagent config set/list/delete	Manage encrypted API keys
supyagent doctor	Diagnose your setup

---

Using Tools

List available tools

supyagent service tools

Filter by provider:

supyagent service tools --provider google
supyagent service tools --provider slack

Run a tool

# Send a Slack message
supyagent service run slack_send_message '{"channel": "#general", "text": "Hello from supyagent"}'

# List calendar events
supyagent service run calendar_list_events '{"maxResults": 10}'

# Create a GitHub issue
supyagent service run github_create_issue '{"owner": "myorg", "repo": "myrepo", "title": "Bug fix", "body": "Details here"}'

You can also use colon syntax (gmail:list_messages) or read args from a file:

echo '{"q": "from:[e-mail]"}' | supyagent service run gmail_list_messages --input -
supyagent service run gmail_list_messages --input args.json

Output format

Every tool returns JSON to stdout:

{
  "ok": true,
  "data": {
    "messages": [
      {"id": "abc123", "from": "[e-mail]", "subject": "Hello", "snippet": "..."}
    ]
  }
}

On error:

{
  "ok": false,
  "error": "Permission denied for gmail_send_message: Forbidden"
}

Status messages go to stderr, so the JSON output is always clean for piping.

---

Generate Skill Files for AI Coding Assistants

Supyagent can generate skill files that let AI coding assistants (Claude Code, Codex CLI, OpenCode, Cursor, Copilot, Windsurf) use your connected services directly.

Auto-detect and generate

supyagent skills generate

This detects AI tool folders (.claude/, .codex/, .agents/, .cursor/, .copilot/, .windsurf/) in the current directory and generates skill files in each.

Generate for a specific tool

# Write to a specific directory
supyagent skills generate -o .claude/skills

# Write to all detected folders without prompting
supyagent skills generate --all

# Preview to stdout
supyagent skills generate --stdout

What gets generated

Each connected integration gets its own skill file. For example, if you have Google and Slack connected, you get:

.claude/skills/
  supy-cloud-gmail/SKILL.md
  supy-cloud-calendar/SKILL.md
  supy-cloud-drive/SKILL.md
  supy-cloud-slack/SKILL.md

Each SKILL.md contains YAML frontmatter and documentation for every tool in that integration:

---
name: supy-gmail
description: >-
  Use supyagent to interact with Gmail. Available actions: list emails
  from gmail inbox, get a specific email by its message id, send an
  email via gmail. Use when the user asks to interact with Gmail.
---

# Gmail

Execute tools: `supyagent service run <tool_name> '<json>'`

### gmail_list_messages

List emails from Gmail inbox.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `maxResults` | integer | no | Number of messages to return |
| `q` | string | no | Search query using Gmail syntax |

​```bash
supyagent service run gmail_list_messages '{"q": "from:[e-mail]", "maxResults": 10}'
​```

After generating, your AI coding assistant will automatically use these tools when you ask it to interact with connected services.

---

Integrate with Agent Frameworks

Supyagent tools can be used from any agent framework. There are two integration paths:

Option A: JSON tool definitions (for LangChain, CrewAI, etc.)

Export your tools as JSON:

supyagent service tools --json

This returns a list of tool definitions with parameter schemas:

[
  {
    "name": "google:gmail_list_messages",
    "description": "List emails from Gmail inbox.",
    "provider": "google",
    "service": "gmail",
    "method": "GET",
    "parameters": {
      "type": "object",
      "properties": {
        "maxResults": {"type": "integer", "description": "Number of messages to return"},
        "q": {"type": "string", "description": "Search query using Gmail syntax"}
      }
    }
  }
]

Convert these into OpenAI function-calling format for your framework:

import json
import subprocess

# Get tool definitions
result = subprocess.run(["supyagent", "service", "tools", "--json"], capture_output=True, text=True)
tools = json.loads(result.stdout)

# Convert to OpenAI function-calling format
openai_tools = [
    {
        "type": "function",
        "function": {
            "name": tool["name"].split(":")[-1],
            "description": tool["description"],
            "parameters": tool["parameters"],
        },
    }
    for tool in tools
]

Option B: Execute tools via subprocess

When the LLM calls a tool, execute it through supyagent:

import json
import subprocess

def execute_supyagent_tool(tool_name: str, arguments: dict) -> dict:
    """Execute a supyagent cloud tool and return the result."""
    result = subprocess.run(
        ["supyagent", "service", "run", tool_name, json.dumps(arguments)],
        capture_output=True,
        text=True,
    )
    return json.loads(result.stdout)

# Example: LLM decides to send an email
result = execute_supyagent_tool("gmail_send_message", {
    "to": "[e-mail]",
    "subject": "Meeting notes",
    "body": "Here are the notes from today...",
})

if result["ok"]:
    print("Email sent:", result["data"])
else:
    print("Error:", result["error"])

Full example: LangChain integration

import json
import subprocess
from langchain_core.tools import StructuredTool

# Load supyagent tools
result = subprocess.run(["supyagent", "service", "tools", "--json"], capture_output=True, text=True)
supyagent_tools = json.loads(result.stdout)

def make_tool(tool_def):
    """Create a LangChain tool from a supyagent tool definition."""
    tool_name = tool_def["name"].split(":")[-1]

    def run_tool(**kwargs):
        result = subprocess.run(
            ["supyagent", "service", "run", tool_name, json.dumps(kwargs)],
            capture_output=True, text=True,
        )
        return result.stdout

    return StructuredTool.from_function(
        func=run_tool,
        name=tool_name,
        description=tool_def["description"],
    )

langchain_tools = [make_tool(t) for t in supyagent_tools]

---

Inbox

View webhook events from connected integrations:

# List unread events
supyagent inbox

# Filter by provider
supyagent inbox -p github

# View a specific event
supyagent inbox -i EVENT_ID

# Archive an event
supyagent inbox -a EVENT_ID

# Archive all
supyagent inbox --archive-all

---

Config Management

Supyagent stores API keys encrypted in ~/.supyagent/config/:

# Set a key interactively
supyagent config set

# Set a specific key
supyagent config set OPENAI_API_KEY

# List stored keys
supyagent config list

# Import from .env
supyagent config import .env

# Export to .env
supyagent config export backup.env

# Delete a key
supyagent config delete MY_KEY

---

Development

git clone https://github.com/ergodic-ai/supyagent
cd supyagent

# Install
uv pip install -e ".[dev]"

# Test
pytest

# Lint
ruff check .

Only 4 runtime dependencies: click, rich, cryptography, httpx.

License

MIT