Skip to main content

Fixie Command-line Interface

The Fixie CLI lets you create and manage Fixie Agents and Document Collections from the command line.


First, ensure you have Node v18 or higher installed:

$ node --version

To run the Fixie CLI, you can use npx fixie@latest:

$ npx fixie@latest --help

Usage: fixie [options] [command]

A command-line client to the Fixie AI platform.

-V, --version output the version number
-u, --url <string> URL of the Fixie API endpoint (default: "https://api.fixie.ai")
-r --raw Output raw JSON instead of pretty-printing.
-h, --help display help for command

deploy [options] [path] Deploy an agent
serve [options] [path] Run an agent locally
user Get information on the current user
auth [options] Authenticate to the Fixie service
config Configuration related commands
corpus|corpora Corpus related commands
agent|agents Agent related commands
help [command] display help for command


The Fixie CLI stores authentication credentials for the Fixie service in the file ~/.config/fixie/config.yaml. You can use the command npx fixie@latest to authenticate to the Fixie CLI for the first time, which will open a browser window to the Fixie Console allowing you to login. Once this is done, you should be able to use all of the Fixie CLI commands.

$ npx fixie@latest auth
👤 You are logged into https://api.fixie.ai as mdw
🔑 Your FIXIE_API_KEY is: eyJhxGcIjibI...

Processing CLI output

The CLI outputs JSON by default, which are the raw responses from the corresponding Fixie platform APIs. You can use the jq command to process this output as you like. For example, to list the IDs and display names of the Document Collections you have access to, you can use something like:

$ npx fixie@latest corpus list | jq '.corpora[] | {corpusId, displayName}'

Corpus commands

You can use the CLI to create, modify, and manange Corpora, also called Document Collections on the web console.

List corpora

To list all of the corpora you have access to:

$ npx fixie@latest corpus list
"corpora": [
"corpusId": "96dae83d-2b4a-475c-99f5-7ccf1fd2fea3",
"displayName": "Wikipedia Article on Foxes",

You can also use the --owner option to limit results to those corpora that are owned by you, owned by your team, or public.

Create a corpus

To create a new, empty Corpus, use:

$ npx fixie@latest corpus create "My Corpus"
"corpusId": "96dae83d-2b4a-475c-99f5-7ccf1fd2fea3",
"displayName": "My Corpus",

Add a Web Source to a Corpus

To add a new Source to a Corpus with a URL:

$ npx fixie@latest corpus sources add 96dae83d-2b4a-475c-99f5-7ccf1fd2fea3 \
"source": {
"corpusId": "96dae83d-2b4a-475c-99f5-7ccf1fd2fea3",
"sourceId": "baf7b88a-d2e5-4b11-83c1-22c3ccee5bb4",

Other options are available to allow you to control the crawl depth, include and exclude URL patterns, and so forth.

Upload static documents to a Corpus

To upload documents directly to a Corpus, use:

$ npx fixie@latest corpus sources upload 96dae83d-2b4a-475c-99f5-7ccf1fd2fea3 \
application/pdf my-document.pdf ...

The MIME type for all uploaded documents provided on the commandline must be the same, but you can run the command multiple times to upload documents of different types.

Querying a Corpus

A Corpus query operation returns the most relevant document chunks for a given query string. It does not process these results in any way -- you need an Agent to answer questions in natural language. However, using this command can be useful for debugging how an Agent is answering questions.

❯ npx fixie@latest corpus query 96dae83d-2b4a-475c-99f5-7ccf1fd2fea3 "What do foxes eat?"
"results": [
"chunkContent": "Foxes are ...",
"score": 0.87836957,
"chunkId": "bb44db73-014d-449d-a61b-94f7c5e54d0b",
"citation": {
"sourceId": "14f212db-85ad-48ee-a81f-572160629753",
"documentId": "ba7199a5-4d12-42c1-be19-2572443b154d",
"publicUrl": "https://en.wikipedia.org/wiki/Fox",
"title": "Fox - Wikipedia"

Agent commands

The Fixie CLI can also be used to create and manage Agents.

List Agents

To list all of the Agents you have access to:

$ npx fixie@latest agent list

Deploy an Agent

You can deploy your own Agents, with custom code, using the Fixie CLI.

See Building an Agent for more details on the Agent development process.

To deploy an Agent, run the following from your Agent source directory:

$ npx fixie@latest agent deploy

Running an Agent locally for debugging

It is often useful to run your Agent locally for debugging purposes.

From your Agent source director, run the following:

$ npx fixie@latest agent serve

This command runs the Agent on your development machine, but establishes a tunnel from the Fixie cloud service back to your dev machine to communicate with the Agent.