CLI Reference

The CLI manages the same server workspaces used by the Web UI. Commands operate on the active server unless you pass --project <id>.

Installation

npm install -g @larkup/cli

pnpm add -g @larkup/cli

npx @larkup/cli <command>

Start a local server

larkup dev

The first run asks for a project name, using my-larkup when you press Enter, then creates the workspace and starts its local server. Later, larkup dev starts the active workspace again. Create another workspace explicitly with larkup dev product-docs.

Add data and rebuild the server

larkup index ./knowledge
larkup dev

index recursively loads supported text, PDF, Word, JSON, and source code files, then streams chunking and embedding progress with a terminal progress bar. It skips .git, .larkup, node_modules, dist, and build directories. The active Project’s document and index-run records are shared with the Web UI, so an indexing run started here appears in the Data and Index views immediately. Use --no-run when you want to load files without rebuilding the vector index:

larkup index ./docs ./src --no-run
larkup index --incremental

Use one simple command for a folder, or narrow it to a file type when needed:

larkup index ./folder                 # all supported files
larkup index ./folder --pdf
larkup index ./folder --json
larkup index ./folder --media         # image, audio, and video
larkup index ./folder --video
larkup index ./folder --extension .json,.pdf

larkup indexing is an alias for larkup index.

Configure AI models

Projects, model settings, and indexing can all be managed from the terminal. Changes are written to the same active Project configuration used by the Web UI.

larkup init product-docs
larkup ai-model --embedding openai/text-embedding-3-small --api-key "$OPENAI_API_KEY"
larkup ai-model --chat openai/gpt-5 --api-key "$OPENAI_API_KEY"
larkup ai-model list --type embedding
larkup ai-model list --type chat
larkup ai-model list --type vision

--apikey is accepted as a shorthand for --api-key. larkup set ai-model is an alias for configuring models. When no model flag is provided, larkup ai-model --api-key <key> updates the active embedding model’s API key.

Media

Images, audio, and video can be added directly:

larkup media ./demo.mp4
larkup index ./media

Image metadata is added to the corpus. Audio and video speech is transcribed into a timestamped, searchable document. Media processing status is streamed in the terminal and persisted to the workspace. Audio and video processing requires the Video & Audio marketplace tool:

larkup marketplace install video-audio
larkup media ./interview.mp3

Configure the tool’s transcription provider and API key in the Web UI before processing audio or video. Pass --no-index to process media without rebuilding the index.

Chat and retrieval

larkup query "How do I authenticate?" --topK 3
larkup chat
larkup chat --model openai/gpt-4o-mini

query prints retrieved chunks. chat opens an interactive conversation grounded in retrieved content and streams the answer as it is generated. --model selects a model for that command only; it must be available through the project’s configured chat provider. Use larkup settings to change the provider or its default model. When the project uses Vercel AI Gateway, provider-prefixed IDs such as anthropic/claude-sonnet-4 are supported. Generated servers also expose POST /query and the streaming POST /chat endpoint, so the same features are available through the TypeScript and Python SDKs.

Corpus documents

larkup documents
larkup documents show <document-id>
larkup documents update <document-id> --file ./revised.md
larkup documents remove <document-id>
larkup documents export --format jsonl --out ./corpus.jsonl

docs is a shorter alias for documents. Updating a document marks it unindexed; run larkup index --incremental afterward.

Marketplace Hub

larkup marketplace
larkup marketplace info video-audio
larkup marketplace install video-audio
larkup marketplace uninstall video-audio

market is a shorter alias for marketplace. The catalog combines local tool manifests with the remote Marketplace Hub and retains an offline fallback catalog.

Generate, test, and deploy

larkup generate --out ./my-larkup-server
larkup test
larkup test --connection
larkup test --endpoint https://rag.example.com --api-key "$LARKUP_API_KEY"
larkup deploy docker --out ./deployment

Deployment targets:

Target	Behavior
`docker`	Generate or export a server ready for Docker. This is the default.
`vercel`	Generate or export a server ready for Vercel.
`export`	Copy the portable server artifact to `--out`.
`local`	Generate and start the standard server in the background.
`agent`	Generate the extendable agent server, or start it with `--start`.

The standard generated server includes retrieval, document APIs, scraping, corpus export, and streaming chat. The agent target remains useful when you need the portable agent manifest and widget surface.

Browser and updates

larkup open
larkup open api
larkup open https://rag.example.com/reference
larkup update --check
larkup update

open opens the Web UI by default. open api opens the active server’s API reference. update --check only reports whether a newer CLI exists; update installs it globally.

Command reference

Command	Description
`larkup dev [name]`	First run: create a workspace and run its local server. Later: run the active workspace. Pass a name to create another workspace.
`larkup init [name]`	Create and activate a server workspace.
`larkup projects`	List all Projects.
`larkup use <projectId>`	Switch the active Project.
`larkup config`	Show configuration and status.
`larkup add-doc`	Add a file or inline text with optional source URL metadata.
`larkup documents`	List, show, update, remove, or export corpus documents.
`larkup index [sources...]`	Load files or folders and build the index.
`larkup ai-model [list]`	Show, list, or configure embedding, chat, and vision models.
`larkup media [sources...]`	Process image, audio, or video files.
`larkup query <question>`	Retrieve the most relevant chunks.
`larkup chat`	Start a streaming terminal chat.
`larkup generate`	Emit a portable standard server.
`larkup serve`	Run the standard server in the foreground.
`larkup marketplace`	List, inspect, install, or uninstall tools.
`larkup deploy [target]`	Prepare or start a deployment target.
`larkup test`	Validate configuration, storage, or an endpoint.
`larkup open [target]`	Open the Web UI, API reference, or URL.
`larkup update`	Check for or install a CLI update.
`larkup settings`	Configure terminal chat models.

Getting Started

Use Cases

Developer Guide

Installation

Start a local server

Add data and rebuild the server

Configure AI models

Media

Chat and retrieval

Corpus documents

Marketplace Hub

Generate, test, and deploy

Browser and updates

Command reference

​Installation

​Start a local server

​Add data and rebuild the server

​Configure AI models

​Media

​Chat and retrieval

​Corpus documents

​Marketplace Hub

​Generate, test, and deploy

​Browser and updates

​Command reference

Installation

Start a local server

Add data and rebuild the server

Configure AI models

Media

Chat and retrieval

Corpus documents

Marketplace Hub

Generate, test, and deploy

Browser and updates

Command reference