askpplx 1.2.2 → 1.3.1

package/README.md

@@ -29,6 +29,15 @@ askpplx "Explain Raft vs Paxos in simple terms"
 
 # web-enabled search with local context
 askpplx "What are breaking changes in React 19 that affect this code? $(cat src/app.tsx)"
+
+# read prompt from stdin (filter style)
+cat article.txt | askpplx -S "Summarize this article"
+
+# extract plain text from JSON response
+askpplx "Node.js LTS version" --json | jq -r '.text'
+
+# list cited source URLs
+askpplx "Latest TypeScript release notes" --json | jq -r '.sources[].url' | sort -u
 ```
 
 ## Agent Rule
@@ -36,11 +45,20 @@ askpplx "What are breaking changes in React 19 that affect this code? $(cat src/
 Add this rule to your `CLAUDE.md` or `AGENTS.md` to enable automatic Perplexity lookups, no need to configure MCPs:
 
 ```markdown
-# Rule: askpplx CLI Usage
+# Rule: `askpplx` CLI Usage
+
+**MANDATORY:** Run `npx -y askpplx --help` at the start of every agent session to learn available options and confirm the tool is working.
+
+Use `askpplx` to query Perplexity, an AI search engine combining real-time web search with advanced language models.
+
+## Why This Matters
 
-Use `askpplx` to query Perplexity, an AI search engine combining real-time web search with advanced language models. Run it via `npx -y askpplx`.
+- **Ground your knowledge:** Your training data has a cutoff date. Real-time search ensures you work with current information—correct API signatures, latest versions, up-to-date best practices.
+- **Save time and resources:** A quick lookup is far cheaper than debugging hallucinated code or explaining why an approach failed. When in doubt, verify first.
+- **Reduce false confidence:** Even when you feel certain, external verification catches subtle errors before they compound into larger problems.
+- **Stay current:** Libraries change, APIs deprecate, patterns evolve. What was correct six months ago may be wrong today.
 
-Use concise prompts for quick facts and focused questions for deeper topics. If results are unexpected, refine your query and ask again.
+## Usage Guidelines
 
-Verification is fast and cheap, so prefer looking up information over making assumptions. Before first use, run `npx -y askpplx --help`.
+Use concise prompts for quick facts and focused questions for deeper topics. If results are unexpected, refine your query and ask again. Verification is fast and cheap—prefer looking up information over making assumptions.
 ```

package/dist/cli.js

@@ -1,8 +1,10 @@
 #!/usr/bin/env node
-import { Command } from "commander";
+import { Command, Option } from "@commander-js/extra-typings";
 import packageJson from "../package.json" with { type: "json" };
 import { clearPerplexityApiKey, getConfigPath, getPerplexityApiKey, maskApiKey, setPerplexityApiKey, } from "./config.js";
 import { runCli } from "./run-cli.js";
+import { collectStdinText } from "./collect-stdin-text.js";
+import { resolveCliPrompt } from "./resolve-cli-prompt.js";
 const usageExamples = `
 About Perplexity:
   Perplexity AI is an AI-powered search engine and answer engine that delivers
@@ -28,28 +30,51 @@ Examples:
   askpplx "Latest news on AI" -c medium
   askpplx "$(cat article.txt)" -s ./summarize.md
   askpplx "$(cat article.txt)" -S "Summarize this article"
+  cat article.txt | askpplx -S "Summarize this article"
   askpplx "Node.js LTS version" --json | jq -r '.text'
   askpplx "Show reasoning" --show-thinking`;
 const program = new Command()
-    .name("askpplx")
+    .name(packageJson.name)
     .description(packageJson.description)
     .version(packageJson.version)
+    .showHelpAfterError("(add --help for additional information)")
+    .showSuggestionAfterError()
     .argument("[prompt]", "The prompt to send to Perplexity Sonar")
     .option("-m, --model <model>", "Model to use", "sonar-reasoning-pro")
     .option("-s, --system <path>", "Path to custom system prompt file")
     .option("-S, --system-text <text>", "System prompt text (overrides -s)")
-    .option("-c, --context <size>", "Search context size: low, medium, high", "high")
+    .addOption(new Option("-c, --context <size>", "Search context size: low, medium, high")
+    .choices(["low", "medium", "high"])
+    .default("high"))
     .option("--json", "Output full API response as JSON (text, sources, usage)")
     .option("--show-thinking", "Show model thinking/reasoning blocks")
-    .option("--no-stream, --no-streaming", "Disable streaming output")
+    .option("--no-stream", "Disable streaming output")
+    .addOption(new Option("--no-streaming", "Alias for --no-stream").hideHelp())
     .addHelpText("after", usageExamples)
     .action(async (prompt, options) => {
-    if (!prompt) {
-        program.help();
-        return;
-    }
     try {
-        await runCli(prompt, options);
+        let stdinText;
+        if (!prompt && !process.stdin.isTTY) {
+            process.stdin.setEncoding("utf8");
+            stdinText = await collectStdinText(process.stdin);
+        }
+        const effectivePrompt = resolveCliPrompt(prompt, stdinText);
+        if (!effectivePrompt) {
+            program.error("Missing prompt.\n" +
+                'Usage: askpplx <prompt> OR cat <file> | askpplx -S "Summarize this article"\n' +
+                "(Note: use -S to provide an instruction with stdin input)", { exitCode: 1 });
+            return;
+        }
+        const cliOptions = {
+            model: options.model,
+            json: Boolean(options.json),
+            system: options.system,
+            systemText: options.systemText,
+            context: options.context,
+            showThinking: Boolean(options.showThinking),
+            stream: options.stream && options.streaming,
+        };
+        await runCli(effectivePrompt, cliOptions);
     }
     catch (error) {
         const message = error instanceof Error ? error.message : "An unexpected error occurred";
@@ -57,7 +82,7 @@ const program = new Command()
         process.exitCode = 1;
     }
 });
-program
+const configCommand = program
     .command("config")
     .description("Manage stored configuration")
     .option("--set-api-key <key>", "Store Perplexity API key")
@@ -68,7 +93,7 @@ program
     try {
         if (options.setApiKey) {
             setPerplexityApiKey(options.setApiKey);
-            console.log("API key stored successfully.");
+            console.error("API key stored successfully.");
         }
         else if (options.showApiKey) {
             const key = getPerplexityApiKey();
@@ -77,14 +102,13 @@ program
         }
         else if (options.clearApiKey) {
             clearPerplexityApiKey();
-            console.log("API key cleared.");
+            console.error("API key cleared.");
         }
         else if (options.path) {
             console.log(getConfigPath());
         }
         else {
-            const configCmd = program.commands.find((c) => c.name() === "config");
-            configCmd?.help();
+            configCommand.help({ error: true });
         }
     }
     catch (error) {
@@ -95,4 +119,4 @@ program
         process.exitCode = 1;
     }
 });
-program.parse();
+await program.parseAsync();

package/dist/collect-stdin-text.d.ts

@@ -0,0 +1 @@
+export declare function collectStdinText(input: AsyncIterable<string>, maxBytes?: number): Promise<string>;

package/dist/collect-stdin-text.js

@@ -0,0 +1,15 @@
+import { Buffer } from "node:buffer";
+const DEFAULT_MAX_STDIN_BYTES = 10 * 1024 * 1024;
+export async function collectStdinText(input, maxBytes = DEFAULT_MAX_STDIN_BYTES) {
+    const chunks = [];
+    let totalBytes = 0;
+    for await (const chunk of input) {
+        totalBytes += Buffer.byteLength(chunk, "utf8");
+        if (totalBytes > maxBytes) {
+            const limitMegabytes = Math.round(maxBytes / 1024 / 1024);
+            throw new Error(`Input too large: exceeds ${String(limitMegabytes)}MB limit`);
+        }
+        chunks.push(chunk);
+    }
+    return chunks.join("");
+}

package/dist/resolve-cli-prompt.d.ts

@@ -0,0 +1 @@
+export declare function resolveCliPrompt(promptArgument: string | undefined, stdinText?: string): string | undefined;

package/dist/resolve-cli-prompt.js

@@ -0,0 +1,9 @@
+export function resolveCliPrompt(promptArgument, stdinText) {
+    const candidate = (promptArgument ?? stdinText)?.trimEnd();
+    if (candidate === undefined)
+        return undefined;
+    const trimmedCandidate = candidate.trim();
+    if (trimmedCandidate.length === 0)
+        return undefined;
+    return candidate;
+}

package/package.json

@@ -2,7 +2,7 @@
   "name": "askpplx",
   "author": "Łukasz Jerciński",
   "license": "MIT",
-  "version": "1.2.2",
+  "version": "1.3.1",
   "description": "Minimal Unix-style CLI for querying Perplexity Sonar API.",
   "repository": {
     "type": "git",
@@ -42,6 +42,7 @@
   },
   "dependencies": {
     "@ai-sdk/perplexity": "^2.0.21",
+    "@commander-js/extra-typings": "^14.0.0",
     "ai": "^5.0.108",
     "commander": "^14.0.2",
     "conf": "^15.0.2",