Ciele CLI

Il comando ciele utilizza le stesse operazioni API della console di amministrazione. La CLI supporta il servizio hosted e le installazioni self-hosted.

Requisiti

Utilizza Node.js 22.6 o versioni successive.
Crea una chiave API dell'organizzazione.

Installazione

Compila e installa il pacchetto standalone da un checkout del repository:

pnpm --dir packages/cli pack --pack-destination ./dist
npm install --global ./packages/cli/dist/ciele-cli-*.tgz
ciele help

Il tarball include le sue dipendenze di runtime. Il comando installato non necessita più del repository.

Dopo che @ciele/cli è stato pubblicato su npm, npm install --global @ciele/cli installa lo stesso artefatto.

I contributori possono anche eseguire node packages/cli/bin/ciele.mjs senza installarlo.

Accedi

Per il servizio hosted, esegui:

ciele login --key "$CIELE_API_KEY"
ciele whoami

Per un'installazione self-hosted, aggiungi il suo public origin:

ciele login \
  --key "$CIELE_API_KEY" \
  --base-url "https://ciele.example.edu"
ciele doctor

Il comando login convalida la chiave prima di scrivere ~/.ciele/config.json. Sui sistemi supportati, il file mode è 0600.

La CLI risolve una chiave in questo ordine:

L'opzione --api-key.
La variabile di ambiente CIELE_API_KEY.
Il file di configurazione salvato.

La CLI utilizza lo stesso ordine per --base-url, CIELE_BASE_URL e l'origine salvata. L'origine ospitata è l'impostazione predefinita finale.

Utilizza l'output dell'automazione

Aggiungi --json a un comando per ottenere un output leggibile da macchina.

Exit code	Significato
`0`	L'operazione è stata completata.
`1`	Il server ha restituito un errore.
`2`	L'input del comando non è valido.
`3`	Autenticazione non riuscita.

ciele doctor verifica l'API discovery, la compatibilità dell'API, la chiave, il relativo Role e la relativa Organization.

Comandi per l'Assistente e per la knowledge

ciele assistants list --all
ciele assistants update <assistant-id> --file assistant-patch.json
ciele flows list <assistant-id>
ciele flows update <flow-id> --file flow-patch.json
ciele collections list <assistant-id>
ciele sources add-file <collection-id> --file handbook.pdf --assistants <assistant-id>
ciele sources get <source-id>
ciele publish status <assistant-id>

Ogni comando che aggiunge conoscenza richiede --assistants. Una Collection non ha un proprietario, quindi questi link sono l'unico elemento che rende le conoscenze accessibili a un Assistant. I comandi sono sources add-text, sources add-url, sources add-file, faqs add e faqs import.

Aggiungi conoscenze senza una Collection

Un nuovo Assistente non ha alcuna Collection, perché l'elenco Collection mostra solo le Collection che contengono le sue Sources. In tal caso, utilizza sources add-org. Inserisce la Source nella Knowledge Library dell'Organization.

ciele sources add-org --url https://example.com/help --assistants <assistant-id>
ciele sources add-org --file handbook.pdf --assistants <assistant-id>
ciele sources add-org --text "Opening hours are 09:00 to 17:00." --assistants <assistant-id>

Fornisci uno tra --url, --file o --text. Il comando richiede --assistants per lo stesso motivo degli altri comandi add.

Collegamenti alle fonti

Una Source risponde per gli Assistants a essa collegati. Questi comandi leggono e modificano i link.

ciele sources list-org
ciele sources link <source-id> --assistants <assistant-id>,<assistant-id>
ciele sources direct-access <source-id> on --assistant <assistant-id>

sources list-org elenca tutte le Source di proprietà dell'Organization, in tutti gli Assistant.

sources link sostituisce il set di link. Un elenco vuoto rimuove tutti i collegamenti e la Source smette di rispondere.

sources direct-access decide se quell'Assistente specifico può fornire al Visitor il file originale.

Cerca nella knowledge base

knowledge search mostra i passaggi che corrispondono a una domanda, indicando il Document e la Source di ciascun passaggio. Non genera una risposta.

ciele knowledge search "How do I connect Salesforce?"
ciele knowledge search "How do I connect Salesforce?" --assistant <assistant-id>
ciele knowledge search "How do I connect Salesforce?" --json

Con --assistant, la ricerca utilizza solo le Sources collegate a quell'Assistente. Senza di esso, la ricerca utilizza l'intera Library. --json restituisce i risultati con il loro rank, score e ID.

Chiedi a un Assistente

assistants ask invia una domanda a un Assistente pubblicato. Il comando mostra la risposta, le Sources citate nella risposta e l'ID della Conversation.

ciele assistants ask <assistant-id> "How do I connect Salesforce?"
ciele assistants ask <assistant-id> "And ServiceNow?" --conversation <conversation-id>

Usa --conversation con l'ID di una risposta precedente per proseguire quella Conversation. Solo la chiave API che ha avviato una Conversation può proseguirla. Con un ID diverso, la domanda avvia una nuova Conversation.

Ogni domanda utilizza un model turn e crea una Conversation. L'Inbox lo mostra con l'etichetta API key quando imposti il filtro Staff conversations su Include staff o Staff only. Il comando termina con un codice di errore quando l'Assistente non è riuscito a rispondere.

Comandi Flow

Scopri cosa può contenere un Flow

ciele flows catalog mostra i trigger, le azioni e i tipi di condizione di questo deployment di Ciele. Mostra anche quali azioni sono consentite da ciascun trigger. Leggilo prima di scrivere un file Flow. Il server rifiuta un trigger, un'azione o un tipo di condizione che non è presente nell'elenco.

È il deployment a fornire questa risposta, non la CLI. Una CLI di versione precedente utilizzata con una versione più recente di Ciele mostra i nuovi elenchi.

ciele flows catalog

Controlla un Flow prima di salvarlo

flows draft verifica una modifica a un Flow. flows validate verifica un Flow completo. Nessuno dei due comandi salva nulla. Entrambi ti mostrano il Flow che Ciele memorizzerebbe.

ciele flows draft --file patch.json --summary "add a refund branch"
ciele flows validate <assistant-id> --file flow.json --rationale "own flow"

Usali soprattutto per un motivo: quando un Flow scrive su un connettore, Ciele aggiunge un'azione di revisione umana prima di quella scrittura. Questi due comandi ti mostrano l'azione aggiunta. Un'operazione di salvataggio lo fa in modo silenzioso.

Osserva un flusso HTTP

Un Flow con il trigger HTTP tiene traccia di ogni chiamata in entrata.

ciele flows runs <flow-id> --limit 20

Le Conversations non includono queste esecuzioni, perché una chiamata in entrata non è una conversazione.

Comandi per i Teammate

Assegna le funzionalità a un Teammate

Un nuovo AI Teammate può rispondere alle domande. Non può agire finché non gli assegni un dominio e non svolge alcun lavoro non supervisionato finché non gli assegni una Routine.

ciele teammates grants <teammate-id>
ciele teammates set-grants <teammate-id> --domains improvements,knowledge
ciele teammates routines <teammate-id>
ciele teammates add-routine <teammate-id> --instruction "Triage new feedback" --cadence daily --hour 8

set-grants invia ogni volta l'insieme completo dei domini. --domains "" li rimuove tutti. Questo comando richiede una chiave API con il ruolo Admin o superiore, perché consente a un agente di modificare i tuoi dati. Gli altri comandi di Teammate richiedono il ruolo Editor.

Un Teammate può avere al massimo cinque Routine.

Configura un teammate con un unico comando

teammates create crea un teammate che risponde alle domande. Non può agire e non svolge alcun lavoro non supervisionato. teammates provision esegue i tre passaggi insieme.

ciele teammates provision --name "Triage" \
  --grants improvements \
  --routine "Triage new feedback:daily:8"

L'ordine è create, poi grant, poi schedule. Se un passaggio non riesce, il comando ti indica dove si è interrotto. Il teammate rimane utilizzabile fino a quel punto.

Una chiave senza il ruolo Admin può creare il teammate. Non può concedere un dominio. Il comando segnala quindi di essersi interrotto nella fase grants.

Progetti e memoria

Un Project è uno spazio di lavoro condiviso. Un AI Teammate associato a un Project legge il documento di memoria di quel Project a ogni turno.

ciele projects list
ciele projects create --name "Q4 migration"
ciele projects get <project-id>
ciele projects set-document <project-id> --file notes.md --note "after review"
ciele teammates memory <teammate-id>
ciele teammates set-memory <teammate-id> --file memory.md --note "corrected"

set-document e set-memory sostituiscono il testo completo. Ciele conserva il testo precedente nella cronologia del documento.

Attività

ciele tasks list --project <project-id> --status to_do,in_progress
ciele tasks list --label <label-id> --due-from 2026-11-01 --due-to 2026-11-30 --q "brief"
ciele tasks list --improvement <improvement-id> --cursor <next-cursor>
ciele tasks create --project <project-id> --title "Draft the launch brief" --due 2026-11-02
ciele tasks get <task-id>
ciele tasks update <task-id> --status in_review --assignee <user-id>
ciele tasks update <task-id> --json '{"labelIds":["<label-id>"],"blockedBy":["<task-id>"]}'
ciele tasks update <task-id> --archive
ciele tasks comment <task-id> --body "Ready for review"
ciele tasks labels
ciele tasks create-label --name "Bug" --color red
ciele tasks update-label <label-id> --color amber
ciele tasks delete-label <label-id> --yes
ciele projects milestones <project-id>
ciele projects set-milestones <project-id> --json '[{"name":"Launch","date":"2026-11-02"}]'
ciele tasks delete <task-id> --yes

set-milestones sostituisce l'elenco completo. Per mantenere un traguardo, invialo di nuovo con il suo ID. tasks delete elimina anche le sottoattività, i commenti e i file della Task. tasks update --archive nasconde la Task e le sue sottoattività. --restore le mostra di nuovo. Quando sono presenti più attività, tasks list mostra il cursore per la pagina successiva. tasks delete-label rimuove la Label da ogni attività. Le attività rimangono.

Non esiste alcun comando per il tuo livello di memoria personale. Una chiave API agisce come il membro che l'ha creata, quindi un comando qui mostrerebbe il documento privato di quel membro. Nella console, vai su Settings e poi su Memory.

Comandi per Operations e Organization

ciele conversations list --assistant <assistant-id>
ciele conversations pin <conversation-id>
ciele messages feedback <message-id> --value -1
ciele improvements list
ciele memories subjects
ciele help-desks list
ciele teammates list
ciele channels list
ciele skills list
ciele quick-texts list
ciele goals list <assistant-id>
ciele alerts list
ciele organization get
ciele members list
ciele members set-role <user-id> --role-id <role-id>
ciele members set-assistants <user-id> --scope selected --assistants <assistant-id>:editor
ciele roles list
ciele roles create --name "Content reviewer" --capabilities knowledge:view,knowledge:edit
ciele roles set-defaults --member <role-id>
ciele invites list
ciele api-keys list
ciele audit-log list --action members.updateRole --from 2026-10-01
ciele providers list
ciele sso connection

I comandi che eliminano i dati richiedono --yes. Il Flow di comportamento predefinito non può essere eliminato.

--role accetta il nome di un Role predefinito. --role-id accetta l'ID di qualsiasi Role, anche di un Role personalizzato. ciele roles list mostra gli ID. ciele whoami mostra inoltre quante funzionalità ha la chiave.

Esegui ciele help per ogni gruppo di comandi e per ogni opzione accettata. Aggiungi --file quando un comando accetta un input JSON completo o un patch.

Esempio di controllo CI

export CIELE_API_KEY="ciele_sk_..."
export CIELE_BASE_URL="https://ciele.example.edu"
ciele publish status "$ASSISTANT_ID" --json

Archivia tutti i valori nell'archivio dei segreti CI. Non scrivere una chiave in un file di workflow.

Bundle dell'Assistente portatile

Export scrive un bundle JSON con versione sullo standard output. Import crea un nuovo Assistant e restituisce un report delle destinazioni di riferimento non risolte.

ciele assistants export <assistant-id> > assistant.json
ciele assistants import assistant.json

I bundle escludono le credenziali e i dati dei Visitor. L'importazione richiede l'accesso in modifica. Configura le credenziali e i riferimenti mancanti prima di pubblicare il nuovo Assistente.

Esportazioni pianificate di Insights

Crea una pianificazione a partire da una definizione JSON. La cadenza settimanale utilizza weekday da zero per la domenica fino a sei per il sabato.

{
  "name": "Weekly Insights",
  "kind": "insights_overview",
  "format": "csv",
  "filters": {},
  "cadence": { "kind": "weekly", "weekday": 1 },
  "hour": 8,
  "recipientMemberIds": ["member-uuid"]
}

ciele exports create --file schedule.json --yes
ciele exports list
ciele exports update <schedule-id> --file patch.json --yes
ciele exports pause <schedule-id> --yes
ciele exports resume <schedule-id> --yes
ciele exports delete <schedule-id> --yes

La cadenza mensile utilizza {"kind":"monthly","day":1}. L'ora è UTC. I destinatari devono essere Membri attuali dell'Organizzazione.

In questa pagina