CLI Reference

Complete reference for every codelore command. Commands work in both local and cloud mode unless noted. Auto-detection: if a .codelore/ folder exists in the current directory or any parent, local mode is used; otherwise cloud mode.

Global flags

Flag	Description
`-h, --help`	Print help for any command
`--version`	Print CLI version

init

codelore init

codelore init [name]

Initializes a new knowledge base. Behavior depends on whether you're logged in:

Logged in: creates a cloud workspace named name (defaults to current directory name) and sets it as active.
Not logged in: creates .codelore/codelore.db in the current directory for local mode.

codelore init              # local mode (no login) or cloud with directory name
codelore init my-project   # cloud workspace named "my-project"

Lesson commands

codelore add

codelore add <path> [-c content] [-m message]

Creates a new lesson or adds a new version to an existing one. Without flags, opens your default editor ($VISUAL or $EDITOR, falls back to notepad / nano).

Flag	Description
`-c, --content`	Lesson content as a string. Skips the editor.
`-m, --message`	Version note (like a commit message). Optional.

codelore add auth/jwt                              # opens editor
codelore add auth/jwt -m "explain token lifetime"  # opens editor, saves note
codelore add auth/jwt -c "JWT secret in env." -m "quick note"

codelore show

codelore show <path>

Prints the current (latest) version of a lesson to stdout: the path, the last-updated timestamp, the version note (if any), and the Markdown content.

codelore show auth/jwt
codelore show db/migrations

codelore edit

codelore edit <path> [-m message]

Opens the current content of a lesson in your editor for modification. Saves a new version on exit.

Flag	Description
`-m, --message`	Version note for the new version.

codelore edit auth/jwt
codelore edit auth/jwt -m "update token expiry"

codelore ls

Lists every lesson in the current knowledge base as an indented tree, derived from the slash-separated paths — much like the output of the tree command.

codelore ls

codelore log

codelore log <path>

Shows the full version history of a lesson, newest first. Each entry shows version number, timestamp, author (cloud), and the version note.

codelore log auth/jwt
codelore log db/migrations

codelore context

codelore context <query>

Searches all lessons for the query string and bundles matching lessons into a single Markdown document printed to stdout. Designed for pasting into AI prompts.

codelore context "authentication"
codelore context "database"
codelore context "rate limiting" > context.md   # save to file

Authentication

ℹ️

These commands only apply to cloud mode. Local mode does not require authentication.

codelore signup

Create a new account. Prompts for email and password (password input is hidden). Saves the auth token to ~/.codelore/config.json on success.

codelore signup

codelore login

codelore login

codelore logout

Clears the saved auth token from ~/.codelore/config.json. You will need to log in again to use cloud mode.

codelore logout

Workspace commands

ℹ️

Cloud mode only. Workspaces are shared knowledge bases accessible by multiple users.

codelore workspace create

codelore workspace create <name>

Creates a new cloud workspace with the given name. You become the owner. The workspace is automatically set as active.

codelore workspace create my-team
codelore workspace create backend-docs

codelore workspace list

Lists all workspaces you belong to (owned or invited). Alias: codelore workspace ls.

codelore workspace list
codelore workspace ls

codelore workspace use

codelore workspace use <name>

Sets the named workspace as active. Subsequent commands (add, show, ls, etc.) will target this workspace.

codelore workspace use my-team
codelore workspace use backend-docs

codelore workspace invite

codelore workspace invite <email>

Invites a user to the currently active workspace by email. They must already have a CodeLore account.

codelore workspace invite teammate@example.com

codelore workspace delete

codelore workspace delete <name>

Permanently deletes a workspace and all its lessons. Only the workspace owner can delete. You will be prompted to type the workspace name to confirm before deletion proceeds.

codelore workspace delete my-team

Sync commands

ℹ️

These commands require both a local .codelore/ database and an active cloud workspace. Run them from a directory that contains or is inside a .codelore/folder.

codelore push

Uploads lessons from the local database to the cloud workspace. For each lesson:

If only local: upload it.
If same hash: skip (already in sync).
If both sides changed: show a diff and prompt to resolve.

Reports a summary: X pushed, Y skipped, Z unresolved.

codelore push

codelore pull

Downloads lessons from the cloud workspace to the local database. Mirror of push:

If only cloud: download it.
If same hash: skip.
If both sides changed: show a diff and prompt to resolve.

codelore pull

Conflict resolution prompt

When a conflict is detected during push or pull, CodeLore displays a unified diff and waits for your input:

Conflict: auth/jwt
--- local
+++ cloud
@@ -1 +1 @@
-JWTs expire after 30 days.
+JWTs expire after 7 days (tightened in v2.4).

[k] keep local  [c] cloud wins  [e] edit manually  [s] skip

Key	Action
`k`	Keep the local version — uploads local content to cloud
`c`	Cloud wins — writes cloud content to local database
`e`	Edit manually — opens your editor with both versions for manual merge
`s`	Skip — leave both sides unchanged, come back later

AI integration

codelore mcp

Starts a Model Context Protocol (MCP) server over stdio so AI tools like Claude Desktop and Cursor can read and write your knowledge base directly. The server targets whichever backend is active (local .codelore/ or your selected cloud workspace) and exposes five tools: get_workspace_info, list_lessons, search_lessons, get_lesson, and add_lesson.

You normally don't run this by hand — your AI tool launches it for you via its MCP config. See the AI Integration guide for setup.

codelore mcp   # usually invoked by your AI client, not run directly

Configuration

Global config is stored in ~/.codelore/config.json. You can inspect it directly, let the CLI manage it via the login/workspace commands, or use the codelore config command.

Field	Default	Description
`api_url`	http://localhost:8080	Base URL for the CodeLore server
`token`	(empty)	JWT auth token saved after login
`workspace`	(empty)	Active cloud workspace name

codelore config

Prints the effective configuration: the server URL (and whether it comes from the file or the environment), your login status, and the active workspace.

codelore config

codelore config set-url

codelore config set-url <url>

Points the CLI at a different server (for example, a self-hosted instance) without editing the file by hand.

codelore config set-url https://app.getcodelore.com
codelore config set-url http://localhost:8080

💡

The CODELORE_API_URL environment variable overrides the stored server URL for a single invocation — handy for scripts or pointing a distributed binary at production without touching config.json.