superacli 1.1.8 → 1.1.10

package/cli/adapters/process.js

@@ -171,16 +171,25 @@ async function execute(cmd, flags, context = {}) {
   }
 
   if (passthroughMode) {
+    // Passthrough mode: use __rawArgs from flags (collected from remaining positional args)
     const passthroughArgs = Array.isArray(flags.__rawArgs) ? flags.__rawArgs : []
     args.push(...passthroughArgs)
   } else {
+    // Normal mode: collect positional values from flags OR from __positionalArgs
     const positionalValues = []
+    
+    // First, try to get positional values from flags (defined args)
     for (const name of positionalNames) {
       if (remainingFlags[name] !== undefined) {
         positionalValues.push(String(remainingFlags[name]))
         delete remainingFlags[name]
       }
     }
+    
+    // Also support __positionalArgs array for commands that need raw positional values
+    if (Array.isArray(flags.__positionalArgs)) {
+      positionalValues.push(...flags.__positionalArgs)
+    }
 
     const flagArgs = []
     if (includeJsonFlag) flagArgs.push(includeJsonFlag)

package/cli/skills-catalog.js

@@ -7,17 +7,27 @@ function dcliDir() {
   return process.env.SUPERCLI_HOME || path.join(os.homedir(), ".dcli")
 }
 
+function supercliDir() {
+  return process.env.SUPERCLI_HOME || path.join(os.homedir(), ".supercli")
+}
+
 function providersFile() {
-  return path.join(dcliDir(), "skills-providers.json")
+  const supercliPath = path.join(supercliDir(), "skills-providers.json")
+  const dcliPath = path.join(dcliDir(), "skills-providers.json")
+  return fs.existsSync(supercliPath) ? supercliPath : dcliPath
 }
 
 function indexFile() {
-  return path.join(dcliDir(), "skills-index.json")
+  const supercliPath = path.join(supercliDir(), "skills-index.json")
+  const dcliPath = path.join(dcliDir(), "skills-index.json")
+  return fs.existsSync(supercliPath) ? supercliPath : dcliPath
 }
 
 function ensureDir() {
   const dir = dcliDir()
   if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true })
+  const supercliDirPath = supercliDir()
+  if (!fs.existsSync(supercliDirPath)) fs.mkdirSync(supercliDirPath, { recursive: true })
 }
 
 function defaultProviders() {
@@ -135,7 +145,7 @@ function syncCatalog() {
       for (const entry of entries) {
         if (!entry || !entry.id || !entry.source_url) continue
         skills.push({
-          id: `${provider.name}:${entry.id}`,
+          id: provider.name + ":" + entry.id,
           provider: provider.name,
           name: entry.name || entry.id,
           description: entry.description || "",
@@ -147,6 +157,34 @@ function syncCatalog() {
       continue
     }
 
+    if (provider.type === "plugin_fs") {
+      const pluginDir = provider.plugin_dir
+      if (!pluginDir || !fs.existsSync(pluginDir)) continue
+      const skillsDir = path.join(pluginDir, "skills")
+      if (fs.existsSync(skillsDir)) {
+        const files = walkDir(skillsDir)
+        for (const filePath of files) {
+          const markdown = fs.readFileSync(filePath, "utf-8")
+          const { frontmatter, body } = parseFrontmatter(markdown)
+          const baseId = baseSkillId(filePath, frontmatter, skillsDir)
+          const heading = body.split("\n").find(l => l.startsWith("# "))
+          const name = frontmatter.skill_name || (heading ? heading.slice(2).trim() : baseId)
+          const description = frontmatter.description || ""
+          const tags = typeof frontmatter.tags === "string" ? frontmatter.tags.split(",").map(t => t.trim()).filter(Boolean) : []
+          skills.push({
+            id: provider.name + ":" + baseId,
+            provider: provider.name,
+            name,
+            description,
+            source_path: filePath,
+            tags,
+            updated_at: new Date().toISOString()
+          })
+        }
+      }
+      continue
+    }
+
     const roots = Array.isArray(provider.roots) ? provider.roots : []
     for (const root of roots) {
       const files = walkDir(root)
@@ -158,9 +196,8 @@ function syncCatalog() {
         const name = frontmatter.skill_name || (heading ? heading.slice(2).trim() : baseId)
         const description = frontmatter.description || ""
         const tags = typeof frontmatter.tags === "string" ? frontmatter.tags.split(",").map(t => t.trim()).filter(Boolean) : []
-
         skills.push({
-          id: `${provider.name}:${baseId}`,
+          id: provider.name + ":" + baseId,
           provider: provider.name,
           name,
           description,
@@ -206,7 +243,6 @@ function getCatalogSkill(providerId) {
   const hit = (idx.skills || []).find(s => s.id === providerId)
   if (!hit) return null
   let markdown = null
-
   if (hit.source_path) {
     if (!fs.existsSync(hit.source_path)) return null
     markdown = fs.readFileSync(hit.source_path, "utf-8")
@@ -215,15 +251,136 @@ function getCatalogSkill(providerId) {
     if (res.error || res.status !== 0) return null
     markdown = (res.stdout || "").trim()
   }
-
   if (!markdown) return null
+  return { ...hit, markdown }
+}
 
+
+
+/**
+ * Get catalog information with provider breakdown
+ */
+function getCatalogInfo() {
+  const idx = readIndex()
+  const providers = listProviders()
+  
+  const providerStats = providers.map(provider => {
+    if (!provider.enabled) {
+      return { name: provider.name, type: provider.type, enabled: false, status: 'disabled' }
+    }
+    
+    let skillsCount = 0
+    let status = 'active'
+    let details = {}
+    
+    if (provider.type === 'plugin_fs') {
+      const pluginDir = provider.plugin_dir
+      if (!pluginDir || !fs.existsSync(pluginDir)) {
+        status = 'missing'
+        details.error = 'Plugin directory not found'
+      } else {
+        const skillsDir = path.join(pluginDir, 'skills')
+        if (fs.existsSync(skillsDir)) {
+          const files = walkDir(skillsDir)
+          skillsCount = files.length
+          details.plugin_dir = pluginDir
+          details.skills_dir = skillsDir
+        } else {
+          status = 'no_skills_dir'
+          details.skills_dir = skillsDir
+        }
+      }
+    } else if (provider.type === 'local_fs' || provider.type === 'repo_fs') {
+      const roots = Array.isArray(provider.roots) ? provider.roots : []
+      for (const root of roots) {
+        if (fs.existsSync(root)) {
+          const files = walkDir(root)
+          skillsCount += files.length
+        }
+      }
+      details.roots = roots
+    } else if (provider.type === 'remote_static') {
+      skillsCount = Array.isArray(provider.entries) ? provider.entries.length : 0
+      details.entries_count = skillsCount
+      details.source_repo = provider.source_repo
+    }
+    
+    return {
+      name: provider.name,
+      type: provider.type,
+      enabled: provider.enabled,
+      status,
+      skills_count: skillsCount,
+      ...details
+    }
+  })
+  
   return {
-    ...hit,
-    markdown
+    index: {
+      version: idx.version,
+      updated_at: idx.updated_at,
+      total_skills: idx.skills.length
+    },
+    providers: providerStats,
+    recent_skills: idx.skills.slice(-5).map(s => ({
+      id: s.id,
+      name: s.name,
+      provider: s.provider,
+      added_at: s.updated_at
+    }))
   }
 }
 
+/**
+ * Describe all provider types with examples
+ */
+function describeProviderTypes() {
+  return {
+    provider_types: [
+      {
+        name: 'local_fs',
+        description: 'Scans local directories for SKILL.md files',
+        example: {
+          name: 'my-skills',
+          type: 'local_fs',
+          roots: ['~/.config/opencode/skills'],
+          enabled: true
+        }
+      },
+      {
+        name: 'repo_fs',
+        description: 'Scans repository directories for SKILL.md files',
+        example: {
+          name: 'repo',
+          type: 'repo_fs',
+          roots: ['.agents/skills', 'docs/skills'],
+          enabled: true
+        }
+      },
+      {
+        name: 'remote_static',
+        description: 'Pre-indexed skills from remote repositories (GitHub)',
+        example: {
+          name: 'visual-explainer',
+          type: 'remote_static',
+          source_repo: 'https://github.com/user/repo',
+          entries: [{ id: 'skill-1', source_url: 'https://raw.githubusercontent.com/...' }]
+        }
+      },
+      {
+        name: 'plugin_fs',
+        description: 'Auto-discovers SKILL.md files from installed plugin skills/ directory',
+        example: {
+          name: 'superbackend',
+          type: 'plugin_fs',
+          plugin_dir: '/path/to/plugins/superbackend'
+        }
+      }
+    ]
+  }
+}
+
+
 module.exports = {
   listProviders,
   addProvider,
@@ -233,5 +390,7 @@ module.exports = {
   syncCatalog,
   listCatalogSkills,
   searchCatalog,
-  getCatalogSkill
+  getCatalogSkill,
+  getCatalogInfo,
+  describeProviderTypes
 }

package/cli/skills.js

@@ -13,7 +13,9 @@ const {
   syncCatalog,
   listCatalogSkills,
   searchCatalog,
-  getCatalogSkill
+  getCatalogSkill,
+  getCatalogInfo,
+  describeProviderTypes
 } = require("./skills-catalog")
 
 function normalizeSkillId(input) {
@@ -179,7 +181,7 @@ function buildTeachSkillMarkdown(options = {}) {
     ]
   }
 
-  return `---\n${renderYamlObject(frontmatter)}\n---\n\n# Instruction\n\nThis skill teaches LLMs how to discover and use SuperCLI capabilities and skill documents:\n\n1. List available capability docs and catalog skills:\n\n\`\`\`bash\nsupercli skills list --json\n\`\`\`\n\n2. Fetch documentation for a specific capability:\n\n\`\`\`bash\nsupercli skills get <namespace.resource.action> --format skill.md\n\`\`\`\n\n3. Parse YAML frontmatter to understand command, arguments, output schema, and metadata.\n\n4. Execute the capability with validated arguments:\n\n\`\`\`bash\nsupercli <namespace> <resource> <action> --arg value --json\n\`\`\`\n\n5. For plugin discovery and remote plugin installs, use:\n\n\`\`\`bash\nsupercli skills get ${PLUGINS_USAGE_SKILL_ID} --format skill.md\n\`\`\`\n\n6. To index skill documents from a local directory (e.g., a project with docs/skills):\n\n\`\`\`bash\n# List current providers\nsupercli skills providers list --json\n\n# Add a local provider for a project\nsupercli skills providers add --name myproject --type local_fs --roots ./myproject/docs/skills\n\n# Sync the catalog to index new skill documents\nsupercli skills sync\n\n# Search skill documents from the new provider\nsupercli skills search <query> --provider myproject\n\n# Remove a provider if needed\nsupercli skills providers remove --name myproject\n\`\`\`\n\n# Examples\n\n\`\`\`bash\nsupercli skills teach --format skill.md\nsupercli skills teach --format skill.md --show-dag\nsupercli skills providers add --name myproject --type local_fs --roots ./myproject/docs/skills\nsupercli skills sync\nsupercli skills search btc --provider myproject\n\`\`\``
+  return `---\n${renderYamlObject(frontmatter)}\n---\n\n# Instruction\n\nThis skill teaches LLMs how to discover and use SuperCLI capabilities and skill documents:\n\n1. List available capability docs and catalog skills:\n\n\`\`\`bash\nsupercli skills list --json\n\`\`\`\n\n2. Fetch documentation for a specific capability:\n\n\`\`\`bash\nsupercli skills get <namespace.resource.action> --format skill.md\n\`\`\`\n\n3. Parse YAML frontmatter to understand command, arguments, output schema, and metadata.\n\n4. Execute the capability with validated arguments:\n\n\`\`\`bash\nsupercli <namespace> <resource> <action> --arg value --json\n\`\`\`\n\n5. For plugin discovery and remote plugin installs, use:\n\n\`\`\`bash\nsupercli skills get ${PLUGINS_USAGE_SKILL_ID} --format skill.md\n\`\`\`\n\n6. To index skill documents from a local directory (e.g., a project with docs/skills):\n\n\`\`\`bash\n# List current providers\nsupercli skills providers list --json\n\n# Add a local provider for a project\nsupercli skills providers add --name myproject --type local_fs --roots ./myproject/docs/skills\n\n# Sync the catalog to index new skill documents\nsupercli skills sync\n\n# Search skill documents from the new provider\nsupercli skills search <query> --provider myproject\n\n# Remove a provider if needed\nsupercli skills providers remove --name myproject\n\`\`\`\n\n7. **Using Positional Arguments** (for commands that require positional values):\n\n\`\`\`bash\n# Some commands require positional arguments instead of named flags\nsupercli <namespace> <resource> <action> <positional1> <positional2> --json\n\n# Example: Delete by ID (positional argument)\nsupercli superbackend waiting-list delete --id <objectId> --quiet\n\n# Example: Passthrough to plugin CLI\nsupercli superbackend _ _ <resource> <command> <args...> --quiet\n\`\`\`\n\n# Examples\n\n\`\`\`bash\nsupercli skills teach --format skill.md\nsupercli skills teach --format skill.md --show-dag\nsupercli skills providers add --name myproject --type local_fs --roots ./myproject/docs/skills\nsupercli skills sync\nsupercli skills search btc --provider myproject\nsupercli superbackend waiting-list delete --id <id> --quiet\nsupercli superbackend _ _ users list --value 10 --quiet\n\`\`\``
 }
 
 function buildPluginsUsageSkillMarkdown(options = {}) {
@@ -339,7 +341,48 @@ function handleSkillsCommand(options) {
       return true
     }
 
-    outputError({ code: 85, type: "invalid_argument", message: "Unknown providers subcommand. Use: list, add, remove, show", recoverable: false })
+    if (action === "describe") {
+      const types = describeProviderTypes()
+      if (humanMode && !flags.json) {
+        console.log("\n  ⚡ Skill Provider Types\n")
+        for (const t of types.provider_types) {
+          console.log("  " + t.name + ":")
+          console.log("    " + t.description)
+          console.log("    Example:")
+          console.log("      " + JSON.stringify(t.example, null, 6))
+          console.log("")
+        }
+      } else {
+        output(types)
+      }
+      return true
+    }
+
+    outputError({ code: 85, type: "invalid_argument", message: "Unknown providers subcommand. Use: list, add, remove, show, describe", recoverable: false })
+    return true
+  }
+
+  if (subcommand === "catalog") {
+    const action = positional[2]
+    if (action === "info") {
+      const info = getCatalogInfo()
+      if (humanMode && !flags.json) {
+        console.log("\n  ⚡ Skills Catalog Info\n")
+        console.log("  Index:")
+        console.log("    Version:", info.index.version)
+        console.log("    Updated:", info.index.updated_at)
+        console.log("    Total Skills:", info.index.total_skills)
+        console.log("\n  Providers:")
+        for (const p of info.providers) {
+          console.log("    - " + p.name + " (" + p.type + "): " + p.skills_count + " skills [" + p.status + "]")
+        }
+        console.log("")
+      } else {
+        output({ catalog: info })
+      }
+      return true
+    }
+    outputError({ code: 85, type: "invalid_argument", message: "Usage: supercli skills catalog info [--json]", recoverable: false })
     return true
   }
 

package/cli/supercli.js

@@ -226,7 +226,7 @@ function renderTopLevelHelp(config) {
       "  MCP: supercli mcp list | supercli mcp add <name> --url <url> | supercli mcp tools --mcp-server <name> | supercli mcp call --mcp-server <name> --tool <tool> | supercli mcp bind --mcp-server <name> --tool <tool> --as <ns.res.act> | supercli mcp doctor --mcp-server <name> | supercli mcp remove <name>",
     );
     console.log(
-      "  Skill Docs: supercli skills list | supercli skills get <id> | supercli skills search --query <q> | supercli skills sync",
+      "  Skill Docs: supercli skills list | supercli skills get <id> | supercli skills catalog info | supercli skills providers describe | supercli skills search --query <q> | supercli skills sync",
     );
     if (config.features?.ask || process.env.OPENAI_BASE_URL) {
       console.log('  AI: supercli ask "<your natural language query>"');
@@ -859,6 +859,26 @@ async function main() {
       return;
     }
 
+    // Handle passthrough positional arguments
+    const passthroughArgs = [];
+    if (cmd.adapterConfig && cmd.adapterConfig.passthrough === true) {
+      // For passthrough commands, collect remaining positional args after namespace.resource.action
+      const cmdPositionalIndex = positional.findIndex((p, i) => 
+        i >= 0 && 
+        positional[i] === namespace &&
+        positional[i + 1] === resource &&
+        positional[i + 2] === action
+      );
+      if (cmdPositionalIndex >= 0) {
+        // Collect all args after namespace resource action
+        for (let i = cmdPositionalIndex + 3; i < positional.length; i++) {
+          passthroughArgs.push(positional[i]);
+        }
+      }
+      // Pass to adapter via __rawArgs
+      uFlags.__rawArgs = passthroughArgs;
+    }
+
     const start = Date.now();
     const result = await execute(cmd, uFlags, {
       server: SERVER || "",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superacli",
-  "version": "1.1.8",
+  "version": "1.1.10",
   "description": "Config-driven, AI-friendly dynamic CLI",
   "license": "MIT",
   "main": "server/app.js",

package/plugins/openhands/plugin.json

@@ -43,10 +43,10 @@
       "adapter": "process",
       "adapterConfig": {
         "command": "openhands",
-        "baseArgs": ["--headless", "-t"],
+        "baseArgs": ["--headless", "--always-approve", "--override-with-envs", "-t"],
         "positionalArgs": ["task"],
         "parseJson": false,
-        "timeout_ms": 15000,
+        "timeout_ms": 180000,
         "missingDependencyHelp": "Please install OpenHands CLI to use this command."
       },
       "args": [
@@ -64,10 +64,10 @@
       "adapter": "process",
       "adapterConfig": {
         "command": "openhands",
-        "baseArgs": ["--headless", "-f"],
+        "baseArgs": ["--headless", "--always-approve", "--override-with-envs", "-f"],
         "positionalArgs": ["file"],
         "parseJson": false,
-        "timeout_ms": 15000,
+        "timeout_ms": 180000,
         "missingDependencyHelp": "Please install OpenHands CLI to use this command."
       },
       "args": [
@@ -85,11 +85,11 @@
       "adapter": "process",
       "adapterConfig": {
         "command": "openhands",
-        "baseArgs": ["--headless", "--json", "-t"],
+        "baseArgs": ["--headless", "--always-approve", "--override-with-envs", "--json", "-t"],
         "positionalArgs": ["task"],
         "stream": "jsonl",
         "parseJson": false,
-        "timeout_ms": 15000,
+        "timeout_ms": 180000,
         "missingDependencyHelp": "Please install OpenHands CLI to use this command."
       },
       "args": [

package/plugins/openhands/skills/quickstart/SKILL.md

@@ -8,6 +8,16 @@ Use this plugin to run OpenHands in headless automation mode.
 - Verify CLI: `openhands --version`
 - Install plugin: `supercli plugins install openhands`
 
+## Environment Setup
+
+Set these environment variables before running headless tasks:
+
+```bash
+export LLM_API_KEY="your-api-key"
+export LLM_MODEL="openai/gpt-4o-mini"  # or another model
+export LLM_BASE_URL="https://openrouter.ai/api/v1"  # optional
+```
+
 ## Common Commands
 
 - Version: `supercli openhands self version`
@@ -15,6 +25,19 @@ Use this plugin to run OpenHands in headless automation mode.
 - Headless task from file: `supercli openhands task file --file ./task.txt`
 - JSONL stream mode: `supercli openhands task json --task "Add tests"`
 
+## Smoke Test Example
+
+```bash
+# Set environment variables
+export LLM_API_KEY="your-openrouter-api-key"
+export LLM_MODEL="openai/gpt-4o-mini"
+export LLM_BASE_URL="https://openrouter.ai/api/v1"
+export PATH="/path/to/venv/bin:$PATH"
+
+# Run a simple task
+supercli openhands task run --task "Create a file called test.txt with 'hello world'"
+```
+
 ## Passthrough
 
 For any unsupported subcommand, use passthrough:

package/plugins/plugins.json

@@ -581,6 +581,16 @@
         "type": "bundled",
         "manifest_path": "plugins/boxlite/plugin.json"
       }
+    },
+    {
+      "name": "pplx",
+      "description": "Perplexity API CLI for online search, research, and Q&A with citations",
+      "tags": ["perplexity", "ai", "search", "research", "llm", "citations", "online"],
+      "has_learn": true,
+      "source": {
+        "type": "bundled",
+        "manifest_path": "plugins/pplx/plugin.json"
+      }
     }
   ]
 }

package/plugins/pplx/README.md

@@ -0,0 +1,95 @@
+# pplx Plugin
+
+Perplexity API CLI plugin for SuperCLI - Fast, non-interactive, agent-first CLI for online search and research with citations.
+
+## Source
+
+- **CLI Repository**: https://github.com/javimosch/pplx
+- **Skill Sync**: Auto-syncs from `.agents/skills/pplx-usage/SKILL.md`
+
+## Installation
+
+```bash
+# Learn about the plugin
+sc plugins learn pplx
+
+# Install from registry
+sc plugins install pplx
+```
+
+## Configuration
+
+Set your Perplexity API key:
+
+```bash
+export PERPLEXITY_API_KEY=pplx-xxxxxxxxxxxxxxxxxxxxxxxx
+```
+
+Or use `--api-key` flag with each command.
+
+Get API key: https://www.perplexity.ai/settings/api
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `sc pplx chat send <message>` | Send a chat completion request |
+| `sc pplx ask send <question>` | Ask a question (simplified chat) |
+| `sc pplx models list` | List available Perplexity models |
+| `sc pplx help json` | Get machine-readable help schema |
+| `sc pplx _ <any>` | Passthrough for any pplx command |
+
+## Examples
+
+```bash
+# Quick question
+sc pplx ask send "What is quantum computing?" --json
+
+# Research with citations
+sc pplx chat send "Latest AI developments 2025" --citations --json
+
+# Deep research
+sc pplx chat send "Climate change research" \
+  --model sonar-deep-research \
+  --citations \
+  --related-questions \
+  --json
+
+# List models
+sc pplx models list --json
+
+# Passthrough mode
+sc pplx _ chat "Question" --model sonar-pro --temperature 0.7
+```
+
+## Available Models
+
+- `sonar` - Fast online search
+- `sonar-pro` - Advanced online search
+- `sonar-deep-research` - Deep research with citations
+- `sonar-reasoning` - Reasoning with search
+- `sonar-reasoning-pro` - Advanced reasoning
+
+## Error Handling
+
+| Exit Code | Type | Action |
+|-----------|------|--------|
+| 0 | success | Parse response |
+| 85 | missing_api_key | Set PERPLEXITY_API_KEY |
+| 87 | authentication_failed | Check API key |
+| 106 | rate_limited | Wait 60s and retry |
+| 105 | timeout | Retry immediately |
+
+## Skills
+
+This plugin includes learn skills:
+
+```bash
+sc plugins learn pplx
+```
+
+Skills are synced from the remote repository automatically.
+
+## License
+
+MIT

package/plugins/pplx/plugin.json

@@ -0,0 +1,123 @@
+{
+  "name": "pplx",
+  "version": "1.0.0",
+  "description": "Perplexity API CLI - Fast, non-interactive, agent-first CLI for online search and research with citations",
+  "source": "https://github.com/javimosch/pplx",
+  "tags": ["perplexity", "ai", "search", "research", "llm", "citations"],
+  "has_learn": true,
+  "learn": {
+    "file": "skills/usage/SKILL.md",
+    "remote": {
+      "repo": "https://github.com/javimosch/pplx",
+      "path": ".agents/skills/pplx-usage/SKILL.md",
+      "sync": true
+    }
+  },
+  "checks": [
+    { "type": "binary", "name": "node" },
+    { "type": "env", "name": "PERPLEXITY_API_KEY", "required": false }
+  ],
+  "commands": [
+    {
+      "namespace": "pplx",
+      "resource": "chat",
+      "action": "send",
+      "description": "Send a chat completion request to Perplexity API",
+      "adapter": "process",
+      "adapterConfig": {
+        "command": "node",
+        "baseArgs": ["cli/bin/pplx.js", "chat"],
+        "positionalArgs": ["message"],
+        "jsonFlag": "--json",
+        "parseJson": true,
+        "missingDependencyHelp": "Set PERPLEXITY_API_KEY env var or use --api-key flag",
+        "pluginDir": "plugins/pplx"
+      },
+      "args": [
+        { "name": "message", "type": "string", "required": true, "description": "The message to send" },
+        { "name": "model", "type": "string", "required": false, "description": "Model to use (sonar, sonar-pro, sonar-deep-research, sonar-reasoning, sonar-reasoning-pro)", "flag": "--model", "default": "sonar" },
+        { "name": "api-key", "type": "string", "required": false, "description": "API key override (overrides PERPLEXITY_API_KEY env var)", "flag": "--api-key" },
+        { "name": "citations", "type": "boolean", "required": false, "description": "Return citations for verification", "flag": "--citations" },
+        { "name": "images", "type": "boolean", "required": false, "description": "Return images", "flag": "--images" },
+        { "name": "related-questions", "type": "boolean", "required": false, "description": "Return related questions", "flag": "--related-questions" },
+        { "name": "search-queries", "type": "boolean", "required": false, "description": "Return search queries used", "flag": "--search-queries" },
+        { "name": "system", "type": "string", "required": false, "description": "System prompt", "flag": "--system" },
+        { "name": "temperature", "type": "number", "required": false, "description": "Temperature (0-1)", "flag": "--temperature" },
+        { "name": "max-tokens", "type": "integer", "required": false, "description": "Maximum tokens in response", "flag": "--max-tokens" },
+        { "name": "json", "type": "boolean", "required": false, "description": "Output in JSON format", "flag": "--json" }
+      ]
+    },
+    {
+      "namespace": "pplx",
+      "resource": "ask",
+      "action": "send",
+      "description": "Ask a question (simplified chat for Q&A)",
+      "adapter": "process",
+      "adapterConfig": {
+        "command": "node",
+        "baseArgs": ["cli/bin/pplx.js", "ask"],
+        "positionalArgs": ["question"],
+        "jsonFlag": "--json",
+        "parseJson": true,
+        "missingDependencyHelp": "Set PERPLEXITY_API_KEY env var or use --api-key flag",
+        "pluginDir": "plugins/pplx"
+      },
+      "args": [
+        { "name": "question", "type": "string", "required": true, "description": "The question to ask" },
+        { "name": "model", "type": "string", "required": false, "description": "Model to use", "flag": "--model", "default": "sonar" },
+        { "name": "api-key", "type": "string", "required": false, "description": "API key override", "flag": "--api-key" },
+        { "name": "citations", "type": "boolean", "required": false, "description": "Return citations", "flag": "--citations" },
+        { "name": "system", "type": "string", "required": false, "description": "System prompt", "flag": "--system" },
+        { "name": "json", "type": "boolean", "required": false, "description": "Output in JSON format", "flag": "--json" }
+      ]
+    },
+    {
+      "namespace": "pplx",
+      "resource": "models",
+      "action": "list",
+      "description": "List available Perplexity models",
+      "adapter": "process",
+      "adapterConfig": {
+        "command": "node",
+        "baseArgs": ["cli/bin/pplx.js", "models"],
+        "jsonFlag": "--json",
+        "parseJson": true,
+        "missingDependencyHelp": "Set PERPLEXITY_API_KEY env var or use --api-key flag",
+        "pluginDir": "plugins/pplx"
+      },
+      "args": [
+        { "name": "api-key", "type": "string", "required": false, "description": "API key override", "flag": "--api-key" },
+        { "name": "json", "type": "boolean", "required": false, "description": "Output in JSON format", "flag": "--json" }
+      ]
+    },
+    {
+      "namespace": "pplx",
+      "resource": "help",
+      "action": "json",
+      "description": "Get machine-readable help schema",
+      "adapter": "process",
+      "adapterConfig": {
+        "command": "node",
+        "baseArgs": ["cli/bin/pplx.js", "help-json"],
+        "parseJson": true,
+        "pluginDir": "plugins/pplx"
+      },
+      "args": []
+    },
+    {
+      "namespace": "pplx",
+      "resource": "_",
+      "action": "_",
+      "description": "Passthrough to execute any pplx CLI command directly",
+      "adapter": "process",
+      "adapterConfig": {
+        "command": "node",
+        "baseArgs": ["cli/bin/pplx.js"],
+        "passthrough": true,
+        "parseJson": false,
+        "pluginDir": "plugins/pplx"
+      },
+      "args": []
+    }
+  ]
+}

package/plugins/pplx/skills/usage/SKILL.md

@@ -0,0 +1,121 @@
+---
+skill_name: "pplx_usage"
+description: "Teaches agents how to use the Perplexity API CLI for online search, research, and Q&A with citations."
+command: "sc skills get pplx.usage"
+tags: ["perplexity", "ai", "search", "research", "llm", "citations", "online"]
+---
+
+# pplx Usage Skill
+
+Use this skill when you need real-time information, research with citations, or online search capabilities through the Perplexity API.
+
+## 1) Learn and Install
+
+```bash
+# Learn about the plugin
+sc plugins learn pplx
+
+# Install the plugin
+sc plugins install pplx
+```
+
+## 2) Configure API Key
+
+```bash
+# Set environment variable (recommended)
+export PERPLEXITY_API_KEY=pplx-xxxxxxxxxxxxxxxxxxxxxxxx
+
+# Or use --api-key flag with each command
+sc pplx chat send "Question" --api-key pplx-xxx
+```
+
+Get API key: https://www.perplexity.ai/settings/api
+
+## 3) Validate Setup
+
+```bash
+# Check version
+sc pplx _ version
+
+# List available models
+sc pplx models list --json
+```
+
+## 4) Common Workflows
+
+### Quick Question
+```bash
+sc pplx ask send "What is quantum computing?" --json
+```
+
+### Research with Citations
+```bash
+sc pplx chat send "Latest developments in AI regulation 2025" --citations --json
+```
+
+### Deep Research
+```bash
+sc pplx chat send "Comprehensive analysis of renewable energy trends" \
+  --model sonar-deep-research \
+  --citations \
+  --related-questions \
+  --search-queries \
+  --json
+```
+
+### List Models
+```bash
+sc pplx models list --json
+```
+
+### Get Help Schema
+```bash
+sc pplx help json
+```
+
+## 5) Available Models
+
+| Model | Use Case |
+|-------|----------|
+| `sonar` | Fast online search |
+| `sonar-pro` | Advanced online search |
+| `sonar-deep-research` | Deep research with citations |
+| `sonar-reasoning` | Reasoning with search |
+| `sonar-reasoning-pro` | Advanced reasoning |
+
+## 6) Error Handling
+
+Exit codes for agent decision-making:
+
+| Code | Type | Action |
+|------|------|--------|
+| 0 | success | Parse response |
+| 85 | missing_api_key | Set PERPLEXITY_API_KEY |
+| 87 | authentication_failed | Check API key validity |
+| 106 | rate_limited | Wait 60s and retry |
+| 105 | timeout | Retry immediately |
+
+## 7) Passthrough Mode
+
+Use passthrough for advanced options:
+
+```bash
+sc pplx _ chat "Question" --model sonar-pro --temperature 0.7 --max-tokens 500
+```
+
+## 8) Remote Skill Sync
+
+This plugin syncs skills from the remote repository:
+
+```bash
+# Skills are auto-synced from https://github.com/javimosch/pplx
+# Manual sync if needed:
+sc skills sync pplx
+```
+
+## Caveats
+
+- Always use `--json` for programmatic parsing
+- API key required (env var or --api-key flag)
+- Rate limits apply (exit code 106)
+- Prefer `sonar-deep-research` for academic/research tasks