superacli 1.1.9 → 1.1.10

package/package.json

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

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