Using the command line

Use codexis-agent-cli to manage projects, chats and saved agents and send questions with attachments. You need the executable available, Node.js 22 or 24 and an API key for an account with an active CODEXIS AI Agent licence. Requests use the key owner's credits.

The examples use Bash or Zsh. Check the command locally:

codexis-agent-cli --help

Sign-in and profilesCopy Anchor Link

Get an API key using the API guide. Enter it at the hidden sign-in prompt. The CLI verifies the key and saves it with the endpoint in a protected local profile.

codexis-agent-cli auth login --profile work --endpoint https://vm.codexis.ai
codexis-agent-cli auth status
codexis-agent-cli auth profile list

Enter the endpoint as the origin https://vm.codexis.ai; the CLI appends /api/v2. Switch the active profile with the command below. The --profile work flag selects a profile for just one invocation.

codexis-agent-cli auth profile use work
codexis-agent-cli auth status --profile work

Scripts can supply the key and endpoint through environment variables. Here, CI_API_KEY contains a key supplied by your secrets manager. These values take precedence over the profile for this invocation and are not saved to it.

CODEXIS_AGENT_API_KEY="$CI_API_KEY" \
CODEXIS_AGENT_ENDPOINT="https://vm.codexis.ai" \
codexis-agent-cli auth status --json --no-input

To explicitly save a key read from standard input, sign in with --token-stdin. Remove a saved profile with the command below.

codexis-agent-cli auth logout --profile old-profile

A project and your first chatCopy Anchor Link

Create a project from JSON on standard input. Save the response and use its actual id to set a variable for later commands.

codexis-agent-cli project create --input - --json > project.json <<'JSON'
{
  "name": "Contract review",
  "description": "Documents for legal review",
  "instructions": "Identify risks and cite sources.",
  "desktopFolders": [],
  "driveFolders": []
}
JSON
PROJECT_ID=$(node -p "JSON.parse(require('node:fs').readFileSync('project.json', 'utf8')).id")
codexis-agent-cli chat create --project "$PROJECT_ID" --title "First review" --json > chat.json
CHAT_ID=$(node -p "JSON.parse(require('node:fs').readFileSync('chat.json', 'utf8')).id")

Set these variables only after successful creation. The chat is ready for its first message. You can select a model with --model when creating it; otherwise your default settings apply.

To edit an existing project, export its editable fields. Change the values in the file before running the update separately. Updating replaces all five fields: name, description, instructions, desktopFolders and driveFolders.

codexis-agent-cli project get "$PROJECT_ID" --editable --json > project-edit.json

codexis-agent-cli project update "$PROJECT_ID" --input project-edit.json

A message with an attachment and streamed answerCopy Anchor Link

Prepare a local file named contract.pdf. Generate the request UUID before sending and keep it in case the connection is interrupted.

REQUEST_ID=$(node -p "require('node:crypto').randomUUID()")
codexis-agent-cli chat send "$CHAT_ID" \
  --message "Summarise the contract and identify risks." \
  --file ./contract.pdf \
  --idempotency-key "$REQUEST_ID" \
  --wait

--file adds an attachment and can be repeated. Read message text with --message-file instructions.txt, or from standard input with --message-file -. For an attachment already uploaded, use --attachment-id with its actual ID.

With --wait, answer text streams to standard output. Acceptance and execution status go to standard error. Without --wait, the command returns an acceptance receipt containing requestId, chatId, userMessageId and assistantMessageId.

Recovering a request and following its progressCopy Anchor Link

When submission has an uncertain outcome, look up the original request first. Use the same CHAT_ID and REQUEST_ID you kept before sending.

codexis-agent-cli chat request get "$CHAT_ID" "$REQUEST_ID" --json > receipt.json

The accepted status confirms acceptance and returns assistantMessageId. rejected includes the rejection reason. For unresolved, check the original request again; a new UUID would identify a different request. After a connection error, check acceptance before resubmitting too.

If the status is accepted, read the answer ID and continue watching:

MESSAGE_ID=$(node -p "JSON.parse(require('node:fs').readFileSync('receipt.json', 'utf8')).assistantMessageId")
codexis-agent-cli chat watch "$CHAT_ID" --message "$MESSAGE_ID" --deadline 600

Ctrl-C or expiry of --deadline ends observation; the remote agent keeps working. The default observation deadline is 600 seconds. To stop execution, send an explicit request and then check its status. Acknowledging the stop request is separate from finishing the stop.

codexis-agent-cli chat stop "$CHAT_ID" --message "$MESSAGE_ID"
codexis-agent-cli chat status "$CHAT_ID" --message "$MESSAGE_ID" --json

Output for scriptsCopy Anchor Link

--json returns one result object. For sending with --wait, it contains receipt and the final snapshot; watching returns the final snapshot itself. --jsonl streams one snapshot object per line, followed by result or error. The chat send --wait --jsonl command also emits an accepted receipt before the snapshots.

codexis-agent-cli chat watch "$CHAT_ID" --message "$MESSAGE_ID" --jsonl
codexis-agent-cli project list --limit 20 --json --read-only

Check the exit code in scripts too. Code 5 and the INPUT_REQUIRED error mean the agent is waiting for an answer or decision. --no-input disables interactive CLI prompts. --read-only prevents remote data changes while allowing reads and observation.

Saving and using an agentCopy Anchor Link

Select an agent and set AGENT_ID to its exact id from the list. Keep the whole identifier, including any prefix. The editable and deletable fields tell you which definitions you can change or delete; the list also includes agents from add-ons.

codexis-agent-cli agent list --all --json

Export a complete editable JSON definition. Edit the file, then run the update separately.

codexis-agent-cli agent get "$AGENT_ID" --editable --json > agent.json

codexis-agent-cli agent update "$AGENT_ID" --input agent.json

To save your own copy, change name to a new name and run create. Both create and update also accept --input - for JSON on standard input. Keep all exported fields; updates merge localizations by language, and empty example-prompt lists preserve existing values.

codexis-agent-cli agent create --input agent.json --json > created-agent.json
AGENT_ID=$(node -p "JSON.parse(require('node:fs').readFileSync('created-agent.json', 'utf8')).id")

When creating a chat, --agent takes the agent's model and jurisdiction settings. Select its instructions for an individual message with --agent-id when sending; repeat that flag to use multiple agents.

codexis-agent-cli chat create --agent "$AGENT_ID" --json > agent-chat.json
AGENT_CHAT_ID=$(node -p "JSON.parse(require('node:fs').readFileSync('agent-chat.json', 'utf8')).id")
codexis-agent-cli chat send "$AGENT_CHAT_ID" --agent-id "$AGENT_ID" --message "Review the assignment." --wait

Delete your own definition with the following command. Check the selected identifier before running it.

codexis-agent-cli agent delete "$AGENT_ID"

Questions, automations and subagentsCopy Anchor Link

When the agent needs input, read the questions or automation proposals for the exact answer. For a question, take toolCallId and revision from the list. For an automation, take toolCallId from the list and obtain its revision from chat workflow get.

codexis-agent-cli chat question list "$CHAT_ID" --message "$MESSAGE_ID" --json
codexis-agent-cli chat workflow list "$CHAT_ID" --message "$MESSAGE_ID" --json

Set TOOL_CALL_ID and REVISION to the actual values of the selected question. For example, answer a question with text:

codexis-agent-cli chat question answer "$CHAT_ID" "$TOOL_CALL_ID" \
  --message "$MESSAGE_ID" --revision "$REVISION" --text "Apply Czech law."

For an automation, read its details first. After reviewing them, choose approve, request-changes with --feedback, or cancel; each decision command requires the reviewed revision. You can list subagents, read their details with get, read messages with messages, or follow progress with watch.

codexis-agent-cli chat workflow get "$CHAT_ID" "$TOOL_CALL_ID" --message "$MESSAGE_ID" --json
codexis-agent-cli chat workflow approve --help
codexis-agent-cli chat subagent list "$CHAT_ID" --message "$MESSAGE_ID" --json
codexis-agent-cli chat subagent watch --help

Catalogues and other commandsCopy Anchor Link

Find models, jurisdictions, tools and automation templates in the catalogues. model get returns model details; model configure validates choices and estimates costs. Repeat its --field key=value flag or supply JSON with --input.

codexis-agent-cli model list --json
codexis-agent-cli model configure --help
codexis-agent-cli jurisdiction list --json
codexis-agent-cli tool list --json
codexis-agent-cli workflow template list --json
codexis-agent-cli auth features --json

Paginated lists return nextCursor. Pass it through --cursor with the same filters to continue. Add --help to see other commands and required arguments, for example for chat, project chats or attachment upload.

Next stepsCopy Anchor Link

See REST API v2 for data objects and operations. To connect these tools to another AI application, continue with the MCP guide.