CLI

Installa la versione corrente su Linux o macOS:

Sono disponibili anche le installazioni tramite Homebrew e dal sorgente Go:

Su Windows, scarica l’archivio windows-amd64 o windows-arm64 corrispondente dall’ultima versione CLI, estrai runapi.exe e aggiungilo al PATH.

Blocca l’installer a una versione o a una directory di installazione quando un deployment richiede un binario riproducibile:

Il programma di installazione accetta anche RUNAPI_VERSION, RUNAPI_INSTALL_DIR, RUNAPI_INSTALL_BASE, RUNAPI_DOWNLOAD_BASE e RUNAPI_SKIP_LIBC_CHECK=1.

Su una workstation, accedi nel browser e conferma la sorgente delle credenziali:

Esegui un’azione su un modello con un input JSON inline o un file JSON:

La maggior parte delle azioni del modello sono asincrone. Attendono un risultato terminale per impostazione predefinita; aggiungi --async per restituire il Task immediatamente e usa wait in seguito:

Ogni comando emette JSON sullo standard output a meno che un’opzione non richieda esplicitamente un valore scalare, come files create --url-only o listen --print-secret. I messaggi di avanzamento e diagnostici rimangono sullo standard error, così JSON può fluire in sicurezza verso jq:

Le azioni del modello accettano esattamente una sorgente di input per richiesta:

Usa runapi <service> <action> --help prima di costruire una richiesta. La CLI installata elenca i campi correnti dell’azione, gli identificatori di modello accettati e i vincoli di validazione.

Queste opzioni globali si applicano a ogni comando:

La forma del comando del modello è runapi <service> <action>. Le azioni sincrone restituiscono la risposta immediatamente. Per le azioni asincrone, il comportamento predefinito è inviare, eseguire il polling e restituire il risultato terminale dell’attività; --async restituisce invece la risposta di creazione.

Per i campi URL multimediali di primo livello, un percorso di file locale leggibile viene caricato prima dell’esecuzione dell’azione del modello. Gli URL http:// e https:// esistenti vengono inviati invariati. Utilizza files create quando hai bisogno di un URL temporaneo riutilizzabile, quando la sorgente è un URL remoto, o quando la sorgente è dati Base64.

L’elenco sopra è l’inventario completo delle azioni in questa versione della CLI. Il contratto esatto di richiesta e risposta di ciascuna azione è disponibile nel Riferimento API, e la guida del comando locale è la fonte per i campi specifici della versione.

Usa get per esaminare lo stato corrente di un Task asincrono senza attendere. Usa wait per eseguire il polling finché non viene completato, fallisce o raggiunge il timeout del comando. Entrambi i comandi richiedono il servizio e l’azione originali affinché la CLI possa selezionare la forma corretta del risultato del Task.

runapi files create mantiene il flusso temporaneo dell’URL di caricamento file. Carica un percorso locale, un URL remoto o una sorgente Base64 e restituisce un URL che scade dopo un’ora.

Le scelte della sorgente si escludono a vicenda. --url-only stampa solo l’URL; omettilo per ricevere la risposta JSON completa.

Usa il ciclo di vita dei File persistenti quando hai bisogno di un file_id stabile anziché di un URL:

content richiede --output; passare - per scrivere i byte esatti del File sullo standard output. Consultare Files and Uploads per i limiti, l’isolamento dell’account e il ciclo di vita REST.

Usa Uploads per inviare una o più Parts prima di comporre il File finale. Create dichiara il conteggio finale dei byte e i metadati; ripeti --part-id in ordine di composizione al momento del completamento:

Ispeziona l’utente autenticato e l’Account selezionato, quindi interroga il saldo e i contatori di spesa:

pricing list legge i Listini Prezzi correnti. Filtra per servizio, azione o modello. pricing quote stima la prenotazione del Task per un servizio e un’azione richiesti; aggiungere --model quando l’azione è specifica per un modello e fornire gli Input di Pricing con --params o --params-file.

I comandi di pricing non richiedono credenziali a meno che la quotazione non faccia riferimento a un Task di origine di proprietà dell’Account.

runapi login apre un flusso di autorizzazione nel browser e salva la credenziale risultante. Per i server e la CI, auth import-token accetta una Chiave API dallo standard input, la verifica per impostazione predefinita e la salva senza esporne il valore nell’elenco dei processi o nella cronologia della shell:

auth import-token --skip-verify supporta la configurazione dell’immagine offline. Utilizzarlo solo quando la verifica non può essere eseguita durante la configurazione; auth status verifica la credenziale attiva in un secondo momento.

La precedenza della chiave API è --api-key, poi RUNAPI_API_KEY, poi il file di configurazione CLI locale. La precedenza del Base URL è --base-url, poi RUNAPI_BASE_URL, poi il Base URL salvato, poi https://runapi.ai. Il file di configurazione è ~/.config/runapi/config.json, oppure $XDG_CONFIG_HOME/runapi/config.json quando XDG_CONFIG_HOME è impostato.

runapi listen riceve i Callback dei Task per una Chiave API selezionata e, facoltativamente, inoltra ogni callback firmato a un endpoint HTTP locale. L’accesso tramite browser è obbligatorio prima di utilizzare le operazioni di ascolto.

L’URL posizionale e --forward-to sono alternative. Il listener scrive ogni corpo di callback firmato sullo standard output. Un’attività con callback_url continua a consegnare a quell’URL e viene anche copiata nel listener locale.

Dopo aver ricevuto un evento listener valido, la CLI lo conferma prima di tentare la richiesta HTTP locale. Ogni evento viene inoltrato localmente una sola volta: le risposte non-2xx e gli errori di connessione vengono segnalati nel terminale, ma non fanno riprodurre l’evento al listener. Questo comportamento di debug locale non modifica i tentativi di consegna per il callback_url di un Task.

Ogni Account può eseguire fino a 100 listener attivi per Chiave di Sottoscrizione Callback e 1.000 listener attivi in totale. Quando viene raggiunto un limite, ferma un listener inattivo oppure attendi e riprova. La risposta dell’API indica se la chiave selezionata, il tuo Account o la capacità complessiva del servizio è esaurita.

Un listener inattivo verifica la presenza di nuovi eventi circa ogni 15-30 secondi. Gli eventi vengono normalmente trovati entro circa 15 secondi e vengono letti immediatamente quando disponibili. Se viene raggiunto un limite, interrompi un listener inattivo o attendi e riprova. Il comportamento di consegna e conferma esistente rimane invariato.

La selezione della chiave avviene nell’ordine: --callback-api-key-id per un singolo comando, callback_api_key_id nel .runapi.toml del progetto, poi un selettore interattivo. La configurazione del progetto viene salvata alla radice Git, o nella directory corrente fuori da un repository Git, e contiene solo l’ID stabile:

Stampa il Listen Signing Secret di una chiave selezionata senza avviare un listener, oppure ruotalo dopo un’esposizione:

La rotazione invalida i listener attivi per la chiave selezionata. Aggiorna ogni verifier locale con il segreto appena generato prima di riavviare il relativo listener.

Installa la skill portabile della CLI RunAPI in un Harness supportato, ispeziona i target supportati o rimuovi una skill installata:

I target integrati sono claude, codex, gemini, openclaw e hermes. install-skill accetta --version per bloccare una versione della skill, --target-dir per una destinazione personalizzata, --source per un repository sorgente e --force per sovrascrivere una directory di skill esistente.

Genera script di completamento per Bash, Zsh, Fish o PowerShell. Ad esempio, carica il completamento Bash nella shell corrente:

Usa runapi --help per elencare i comandi, runapi <command> --help per le opzioni di un comando e runapi <service> <action> --help per i campi di un’azione del modello.

I comandi terminano con un codice diverso da zero che gli script possono gestire:

Per i campi di richiesta, i valori di stato del Task, i payload dei Callback, i corpi degli errori e la gestione dei limiti di frequenza, prosegui con il Riferimento API. Utilizza gli SDK quando lo stesso flusso di lavoro appartiene a un’applicazione.