Ciele CLI

The ciele command uses the same API operations as the administrator console. The CLI supports the hosted service and self-hosted installations.

Requirements

• Use Node.js 22.6 or later.
• Create an Organization API key.

Install

Build and install the standalone package from a repository checkout:

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

The tarball includes its runtime dependencies. The installed command no longer needs the repository.

After @ciele/cli is published to npm, npm install --global @ciele/cli installs the same artifact.

Contributors can also run node packages/cli/bin/ciele.mjs without installing it.

Sign in

For the hosted service, run:

ciele login --key "$CIELE_API_KEY"
ciele whoami

For a self-hosted installation, add its public origin:

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

The login command validates the key before it writes ~/.ciele/config.json. On supported systems, the file mode is 0600.

The CLI resolves a key in this order:

1. The --api-key option.
2. The CIELE_API_KEY environment variable.
3. The saved configuration file.

The CLI uses the same order for --base-url, CIELE_BASE_URL, and the saved origin. The hosted origin is the final default.

Use automation output

Add --json to a command to receive machine-readable output.

ciele doctor verifies API discovery, API compatibility, the key, its Role, and its Organization.

Assistant and knowledge commands

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>

Every command that adds knowledge needs --assistants. A Collection has no owner, so these links are the only thing that puts the knowledge in the reach of an Assistant. The commands are sources add-text, sources add-url, sources add-file, faqs add, and faqs import.

Add knowledge without a Collection

A new Assistant has no Collection, because the Collection list shows only the Collections that hold its Sources. Use sources add-org in that case. It puts the Source in the Knowledge Library of the 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>

Give one of --url, --file, or --text. The command needs --assistants for the same reason as the other add commands.

Source links

A Source answers for the Assistants linked to it. These commands read and change the links.

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 lists every Source the Organization owns, across all Assistants.

sources link replaces the link set. An empty list removes every link, and the Source stops answering.

sources direct-access decides whether that one Assistant can give a Visitor the original file.

Search the knowledge

knowledge search shows the passages that match a question, with the Document and the Source of each passage. It does not generate an answer.

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

With --assistant, the search uses only the Sources linked to that Assistant. Without it, the search uses the full Library. --json gives the results with their rank, score, and IDs.

Ask an Assistant

assistants ask sends a question to a published Assistant. The command shows the answer, the Sources that the answer cites, and the ID of the Conversation.

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

Use --conversation with the ID from an earlier answer to continue that Conversation. Only the API key that started a Conversation can continue it. With a different ID, the question starts a new Conversation.

Each question uses a model turn and creates a Conversation. The Inbox shows it with the API key label when you set the Staff conversations filter to Include staff or Staff only. The command exits with an error code when the Assistant could not answer.

Flow commands

Find out what a Flow can contain

ciele flows catalog shows the triggers, the actions, and the condition kinds of this Ciele deployment. It also shows which actions each trigger permits. Read it before you write a Flow file. The server refuses a trigger, an action, or a condition kind that is not in the list.

The deployment gives this answer, not the CLI. An older CLI against a newer Ciele shows the new lists.

ciele flows catalog

Check a Flow before you save it

flows draft checks a change to a Flow. flows validate checks a complete Flow. Neither command saves anything. Both show you the Flow that Ciele would store.

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

Use them for one reason above all: when a Flow writes to a connector, Ciele adds a human review action before that write. These two commands show you the added action. A save does it silently.

Watch an HTTP flow

A Flow with the HTTP trigger keeps a record of each inbound call.

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

Conversations do not include these runs, because an inbound call is not a conversation.

Teammate commands

Give a Teammate its capabilities

A new AI Teammate can answer questions. It cannot act until you grant it a domain, and it does no unattended work until you give it a 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 sends the complete set of domains each time. --domains "" removes all of them. This command needs an API key with the Admin Role or higher, because it permits an agent to change your data. The other Teammate commands need the Editor Role.

A Teammate can have a maximum of five Routines.

Set up a teammate in one command

teammates create makes a teammate that answers questions. It cannot act, and it does no unattended work. teammates provision does the three steps together.

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

The order is create, then grant, then schedule. If a step fails, the command tells you where it stopped. The teammate stays usable up to that point.

A key without the Admin Role can create the teammate. It cannot grant a domain. The command then reports that it stopped at the grants step.

Projects and memory

A Project is a shared workspace. An AI Teammate that is attached to a Project reads the memory document of that Project in each turn.

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 and set-memory replace the full text. Ciele keeps the previous text in the history of the document.

There is no command for your own memory layer. An API key operates as the member who made it, so a command here would show the private document of that member. Use Settings, then Memory, in the console.

Operations and Organization commands

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 goals list <assistant-id>
ciele alerts list
ciele organization get
ciele members list
ciele invites list
ciele api-keys list
ciele providers list
ciele sso connection

Commands that delete data require --yes. The Default behavior Flow cannot be deleted.

Run ciele help for every command group and accepted option. Add --file when a command accepts a complete JSON input or patch.

Example CI check

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

Store all values in the CI secret store. Do not write a key in a workflow file.