LambdaZen Local

LambdaZen Local is the official command-line tool for syncing LambdaZen concept repositories to and from your local file system. It works like Git for LambdaZen — clone a concept hierarchy, edit the unpacked files locally, then push your changes back to the cloud.

Requirements

• Python 3.9 or later
• A LambdaZen account with API access (LZ_API_KEY and LZ_CJS_TOKEN)

Installation

pip install lambdazen-local

This installs the lzlocal command globally into your Python environment.

Quick Start

# 1. Save your credentials
lzlocal configure

# 2. Clone a concept repository
lzlocal clone /myuser/myrepo/rootuuid/ ./my-project

# 3. Edit files inside my-project/files/

# 4. Push your changes back to the cloud
lzlocal push ./my-project

Credentials

LambdaZen Local needs two credentials to talk to the cloud:

Option 1 — lzlocal configure (recommended)

Run once per user/environment to save credentials permanently to ~/.lzlocal/.env. Credentials are always stored per-user so multiple environments can coexist.

lzlocal configure
# Prompts:
#   Username (e.g. clouddev, cloudqa): clouddev
#   LZ_API_KEY: ...
#   LZ_CJS_TOKEN: ...

Pass values directly to skip interactive prompts:

lzlocal configure --user clouddev --api-key DEV_KEY --cjs-token DEV_TOKEN
lzlocal configure --user cloudqa  --api-key QA_KEY  --cjs-token QA_TOKEN

LambdaZen Local automatically selects the right key based on the user segment in the repository URI — e.g. /clouddev/myrepo/... uses LZ_API_KEY_CLOUDDEV.

Option 2 — Environment variables

Set variables in your shell before running any command:

export LZ_API_KEY=your_api_key
export LZ_CJS_TOKEN=your_cjs_token
lzlocal clone /myuser/myrepo/rootuuid/ ./my-project

Option 3 — .env file in the current directory

Create a .env file next to where you run lzlocal:

LZ_API_KEY=your_api_key
LZ_CJS_TOKEN=your_cjs_token

Priority order (highest wins): real environment variables → .env in CWD → ~/.lzlocal/.env

Project Layout

After cloning, your project directory looks like this:

my-project/
  concepts/      ← raw concept JSON files downloaded from the cloud (do not edit)
  files/         ← unpacked, human-readable files (EDIT THESE)
  deps/          ← read-only dependency concepts referenced by your concepts
  concepts.csv   ← index mapping local UUIDs to cloud URIs (do not edit)
  files.csv      ← index mapping file paths to concepts (do not edit)

Only edit files inside files/. The concepts/, deps/, concepts.csv, and files.csv entries are managed automatically by lzlocal.

Command Reference

configure — Save credentials

lzlocal configure [--api-key KEY] [--cjs-token TOKEN] [--user USER]

clone — Clone a repository from the cloud

Downloads a concept hierarchy from the LambdaZen cloud into a new local directory.

lzlocal clone ROOT_URI CONCEPTS_PATH [--endpoint URL]

Examples:

lzlocal clone /clouddev/myrepo/abc123/ ./my-project
lzlocal clone /clouddev/myrepo/abc123/ ./my-project --endpoint https://custom.lambdazen.com

pull — Pull latest changes from the cloud

Refreshes all concepts in an existing local project with the latest versions from the cloud. Fails if you have local changes that conflict with incoming cloud changes.

lzlocal pull CONCEPTS_PATH [--ignore-conflicts] [--endpoint URL]

Examples:

lzlocal pull ./my-project
lzlocal pull ./my-project --ignore-conflicts

pull-concept — Pull a single concept

Downloads one specific concept from the cloud and unpacks it, leaving all other concepts untouched.

lzlocal pull-concept CONCEPTS_PATH CONCEPT_URI [--endpoint URL]

Example:

lzlocal pull-concept ./my-project /clouddev/myrepo/abc123/

push — Push all local changes to the cloud

Packs modified files back into concept JSONs and uploads all changed concepts. Fails if the cloud has newer versions of the same concepts (conflict detection).

lzlocal push CONCEPTS_PATH [--file FILE] [--ignore-conflicts] [--endpoint URL]

Examples:

lzlocal push ./my-project
lzlocal push ./my-project --file "_Folder Name_/script.jsx"
lzlocal push ./my-project --ignore-conflicts

push-concept — Push a single concept to the cloud

Packs and uploads one specific concept by its cloud URI, leaving all other concepts untouched.

lzlocal push-concept CONCEPTS_PATH CONCEPT_URI [--ignore-conflicts] [--endpoint URL]

Example:

lzlocal push-concept ./my-project /clouddev/myrepo/abc123/

diff — Diff local vs cloud

Compares every local concept against the current cloud version and reports what would change if you ran push. Does not modify anything.

lzlocal diff CONCEPTS_PATH [--quiet] [--endpoint URL]

Examples:

lzlocal diff ./my-project
lzlocal diff ./my-project --quiet

local-diff — Diff two local concept directories

Compares two local concept directories against each other. Useful for reviewing changes between a dev and a QA clone of the same repository.

lzlocal local-diff SOURCE_PATH TARGET_PATH [--quiet] [--reverse]

Examples:

lzlocal local-diff ./my-project-dev ./my-project-qa
lzlocal local-diff ./my-project-dev ./my-project-qa --quiet
lzlocal local-diff ./my-project-dev ./my-project-qa --reverse

git-diff — Diff local vs a git repository

Compares a local concept directory against concepts stored in a git repository. Useful when concepts are also tracked in version control.

lzlocal git-diff CONCEPTS_PATH GIT_PATH [--quiet] [--reverse]

Example:

lzlocal git-diff ./my-project ./my-git-repo

unpack — Unpack concept JSONs to files (advanced)

Re-runs the unpack step that converts raw concept JSONs in concepts/ into the editable files in files/. Normally called automatically by pull and pull-concept.

lzlocal unpack CONCEPTS_DIR [--ignore-conflicts]

pack — Pack files back into concept JSONs (advanced)

Re-runs the pack step that reads edited files in files/ and writes them back into the concept JSONs in concepts/. Normally called automatically by push.

lzlocal pack CONCEPTS_DIR [--ignore-conflicts] [--endpoint URL]

upload-concept — Upload a single concept JSON file (debugging)

Uploads a raw concept JSON file directly to the cloud. Intended for debugging.

lzlocal upload-concept FILENAME --repo REPO_URI [--endpoint URL]

Typical Workflows

Start a new project

lzlocal configure                                      # one-time credential setup
lzlocal clone /clouddev/myrepo/rootuuid/ ./my-project  # download from cloud
cd my-project/files
# ... edit files ...
lzlocal push ../                                       # push changes back

Daily sync cycle

lzlocal diff ./my-project                  # check what's changed
lzlocal pull ./my-project                  # get latest from cloud
# ... make edits in my-project/files/ ...
lzlocal diff ./my-project                  # review your changes before pushing
lzlocal push ./my-project                  # upload to cloud

Refresh a single concept without pulling everything

lzlocal pull-concept ./my-project /clouddev/myrepo/someuuid/

Compare dev and QA environments

lzlocal clone /clouddev/myrepo/rootuuid/ ./project-dev
lzlocal clone /cloudqa/myrepo/rootuuid/  ./project-qa
lzlocal local-diff ./project-dev ./project-qa

MCP Servers

LambdaZen exposes its tooling to AI assistants such as Claude Code through two MCP servers. Projects opened with the GUI's Open in Claude Code, or set up with lzlocal clone / pull, get both in their .mcp.json:

Full reference (tools, resources, skills, security model, configuration, troubleshooting): docs/LambdaZen-MCP-Servers.md.

Starting the local server

pip:

lzlocal-mcp /path/to/project

Windows EXE:

LambdaZenLocal.exe mcp /path/to/project

Local server tools

The sync tools run the same code as the CLI commands (src/sync/ops.py) and return JSON: success, error_code (e.g. DETECTED_CONFLICT), error, log (captured output) plus tool-specific fields. Read-only tools are allow-listed in the generated .claude/settings.json; the others ask before running.

Cloud server and skills

The cloud server is the concept /cloud/ide/-4B8VgYKgjBXeaSzs0ror8/ (https://ide.lambdazen.com/eval/rest/cloud/ide/-4B8VgYKgjBXeaSzs0ror8/mcp?secumode=embeded; override with LZ_CLOUD_MCP_URI). Requests carry the user's LZ_API_KEY (authorization header) and LZ_CJS_TOKEN (cjstoken cookie).

It also serves the LambdaZen skills (Claude Skill concepts listed in the server concept's skills property): through the MCP Skills extension (skills/list, skills/get, skill:// resources with SHA-256 manifests) for clients that support it, and through the list_skills / get_skill tools plus its initialization instructions for clients that don't (Claude Code today).

Conflict Handling

LambdaZen Local detects conflicts in two directions:

• Pull conflicts — the cloud has a newer version of a concept that you have also modified locally. Use --ignore-conflicts to overwrite your local changes with the cloud version.
• Push conflicts — the cloud has a newer version of a concept than the one you started from. Use --ignore-conflicts to force-overwrite the cloud with your local version.

When a conflict is detected, the command exits with a non-zero status and prints the affected URIs. Resolve by either discarding one side, or using --ignore-conflicts deliberately.

License

Proprietary — © LambdaZen Technology Corp. All rights reserved.