Perplexity ha rilasciato pplx, un client ufficiale da riga di comando per la sua Search API che porta nel terminale, in formato JSON, risultati di ricerca web fondati su fonti e testo estratto dalle pagine. Secondo la documentazione del progetto, lo strumento è progettato sia per utenti umani sia per agenti di coding.

Il client non è un’interfaccia di chat. Non offre una modalità conversazionale, selezione del modello o risposte sintetizzate. Espone invece le funzionalità della Search API tramite un flusso di lavoro da riga di comando vincolato e con un formato di output prevedibile. Questa distinzione è importante per l’automazione: script e agenti possono consumare risultati di ricerca e recupero come dati strutturati senza dipendere da una sessione del browser o dall’analisi di una risposta di chat in linguaggio naturale.

Due comandi e un contratto JSON rigoroso

pplx fornisce esattamente due superfici operative. pplx search web esegue una ricerca web in tempo reale, mentre pplx content fetch recupera un URL e restituisce testo di pagina ripulito.

L’Agent Skill ufficiale di pplx-cli definisce il contratto di output per questi comandi. Una richiesta riuscita termina con codice 0 e scrive esattamente un oggetto JSON su stdout. Per la ricerca, la risposta ha la forma {hits: [{url, title, domain, snippet, ...}], total, saved_to?}.

Gli errori sono gestiti separatamente. Qualsiasi errore termina con codice 1, lascia stdout vuoto e scrive un oggetto di errore JSON su stderr nella forma {"error":{"code","message","command","hint"?}}. I codici di errore documentati includono AUTHENTICATION, UNKNOWN_ARGUMENT, ARGUMENT_ERROR e BAD_REQUEST. L’Agent Skill segnala che l’elenco non è esaustivo, quindi i chiamanti dovrebbero diramare la logica su error.code anziché presumere che compaiano solo quei codici. Anche la separazione tra stdout e stderr segue un modello Unix comune, rendendo più semplice per i processi chiamanti distinguere i dati riusciti dagli errori operativi.

Installazione e piattaforme supportate

L’installazione viene fornita tramite un unico comando shell che invia uno script di installazione a sh. Lo script install.sh scarica manifest.json dall’ultima release ed estrae tag e versione. Quindi vincola tutti i download rimanenti a quel tag, esplicitamente per evitare conflitti con una pubblicazione simultanea.

Lo script scarica SHA256SUMS e il binario appropriato per la piattaforma, verifica il checksum e installa il binario in ~/.local/bin/pplx. Non richiede sudo. Una ricevuta viene scritta in ~/.config/pplx/pplx-receipt.json, ma solo dopo che il binario installato è stato eseguito con successo.

Il supporto delle piattaforme è limitato a tre target: macOS su Apple Silicon, Linux x86_64 e Linux arm64. Le piattaforme non supportate terminano con un errore. Non esiste una build per Windows né una build per macOS Intel.

Budget dei token per i flussi di lavoro degli agenti

Una delle funzioni più orientate agli agenti è la gestione del budget dei token. L’opzione --output-dir scrive l’intero set di risultati in un file JSON, mentre --stdout-preview[=<CHARS>] tronca i campi stringa lunghi in stdout e aggiunge marcatori ...<truncated>.

L’Agent Skill evidenzia una limitazione importante: --stdout-preview non ha effetto se non è configurata anche una directory di salvataggio. Tronca stdout solo quando il risultato completo viene salvato tramite --output-dir o $PPLX_OUTPUT_DIR. Se usata da sola, restituisce un output a dimensione completa, e i singoli risultati possono pesare diversi kilobyte ciascuno.

I risultati di ricerca salvati vengono scritti in {dir}/web/{rand}.json, mentre i risultati di fetch vengono scritti in {dir}/fetch/{rand}.json. I file vengono scritti solo dopo una richiesta riuscita. La variabile d’ambiente PPLX_OUTPUT_DIR può impostare un valore predefinito per l’area di lavoro, così il flag della directory non deve essere ripetuto. Questo design consente ai flussi di lavoro automatizzati di conservare artefatti completi su disco passando al contempo un’anteprima più piccola attraverso la finestra di contesto o il flusso di log.

Per il recupero dei contenuti, la documentazione aggiunge un controllo di correttezza più che un controllo dei costi: gli utenti dovrebbero verificare error e is_paywall nell’output prima di fidarsi del contenuto recuperato. L’opzione --html aggiunge un campo raw_html recuperato in tempo reale tramite crawler, mentre --no-cache forza un recupero live.

Anche l’autenticazione è rilevante per l’uso automatizzato. pplx auth login è solo TTY, quindi agenti e ambienti CI devono esportare PERPLEXITY_API_KEY. La fatturazione della Search API è indicata a $5.00 per 1.000 richieste, con un limite di 50 QPS su ogni livello di utilizzo.

Le fonti citate dal report originale includono perplexityai/perplexity-cli, pplx-cli SKILL.md, api-platform-developers, prezzi della Perplexity API, limiti di frequenza e livelli di utilizzo e la guida rapida alla Search API.