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_KEYandLZ_CJS_TOKEN)
Installation
pip (cross-platform)
pip install lambdazen-local
This installs two commands: lzlocal (CLI and MCP entry point) and lzlocal-mcp (MCP server directly).
Windows standalone EXEs
Download lzlocal.exe and lzlocalw.exe and place them in the same directory on %PATH%.
| EXE | Purpose |
|---|---|
lzlocal.exe |
Console — CLI commands and MCP server. Behaves identically to the lzlocal pip script. |
lzlocalw.exe |
Windowed — GUI only. Launch directly to open the settings and project manager window. |
Quick Start
Step 1 — Create a workspace
A workspace is a directory that holds one or more cloned projects. Mark it once:
cd /path/to/my-workspace
lzlocal configure --workspace
Step 2 — Save credentials
lzlocal configure --credentials
# Prompts:
# Username (e.g. clouddev, cloudqa): clouddev
# LZ_API_KEY: ...
# LZ_CJS_TOKEN: ...
Pass values directly to skip interactive prompts:
lzlocal configure --credentials --user clouddev --api-key DEV_KEY --cjs-token DEV_TOKEN
Credentials are saved to the workspace .env. Multiple users can coexist — LambdaZen Local selects the right key based on the user segment in the repository URI (e.g. /clouddev/myrepo/... uses LZ_API_KEY_CLOUDDEV). A generic LZ_API_KEY / LZ_CJS_TOKEN without a user suffix is also supported as a fallback.
Step 3 — Clone a repository
cd /path/to/my-workspace
lzlocal clone /clouddev/myrepo/rootuuid/
# clones into ./clouddev-myrepo/ (override with --dirname NAME)
Step 4 — Edit and push
# Edit files inside my-workspace/clouddev-myrepo/files/
lzlocal push clouddev-myrepo/
Credentials
All credentials live in the workspace .env file, written by lzlocal configure --credentials or the Windows GUI. There is no fallback to shell environment variables.
Finding your credentials
Log in to ide.lambdazen.com as the relevant user, click the LambdaZen Local icon (computer icon, bottom left), and copy the API Key and CJS Token from the popup.
Project Layout
After cloning, your project directory looks like this:
my-workspace/
.env ← workspace credentials and settings (managed by lzlocal configure)
clouddev-myrepo/
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)
.mcp.json ← the two LambdaZen MCP servers (written on clone/pull)
.claude/ ← Claude Code settings (written on clone/pull)
Only edit files inside files/. Everything else is managed automatically by lzlocal.
Command Reference
--version — Show the installed version
lzlocal --version
configure — Configure lzlocal settings
Mark a directory as a workspace
lzlocal configure --workspace
Creates or updates a .env in the current directory with LZLOCAL_DIR_TYPE=WORKSPACE. Run this once in the directory that will hold your cloned projects.
Save credentials
lzlocal configure --credentials [--user USER] [--api-key KEY] [--cjs-token TOKEN]
Saves credentials to the workspace .env (the current directory if it is a workspace, or the parent if it is a project). Each value is prompted interactively if not supplied as a flag.
--workspace and --credentials can be combined in a single command.
clone — Clone a repository from the cloud
lzlocal clone ROOT_URI [--dirname NAME] [--yes]
Downloads a full concept hierarchy from the cloud into a new subdirectory of the current workspace. Run from the workspace directory.
| Argument | Description |
|---|---|
ROOT_URI |
URI of the root concept, e.g. /myuser/myrepo/rootuuid/ |
--dirname NAME |
Directory name for the cloned project (default: <user>-<repo>) |
--yes / -y |
Skip the confirmation prompt when cloning a production (non-dev/non-qa) repository |
Example:
cd /path/to/my-workspace
lzlocal clone /clouddev/myrepo/abc123/
# clones into ./clouddev-myrepo/
lzlocal clone /clouddev/myrepo/abc123/ --dirname my-project
# clones into ./my-project/
pull — Pull latest changes from the cloud
lzlocal pull [--ignore-conflicts]
Refreshes all concepts in an existing project with the latest versions from the cloud.
| Argument | Description |
|---|---|
--ignore-conflicts |
Overwrite local changes with cloud versions (use with care) |
cd ./clouddev-myrepo && lzlocal pull
lzlocal pull --ignore-conflicts
pull-concept — Pull a single concept
lzlocal pull-concept CONCEPT_URI
Downloads one concept, updates it in concepts/, and unpacks its files into files/. The concept must already exist in concepts.csv.
| Argument | Description |
|---|---|
CONCEPT_URI |
Cloud URI of the concept to refresh, e.g. /myuser/myrepo/uuid/ |
cd ./clouddev-myrepo && lzlocal pull-concept /clouddev/myrepo/abc123/
push — Push local changes to the cloud
lzlocal push [--file FILE] [--ignore-conflicts]
Packs modified files back into concept JSONs and uploads changed concepts.
| Argument | Description |
|---|---|
--file FILE |
Push only this file (path relative to files/) |
--ignore-conflicts |
Overwrite cloud versions with local changes (use with care) |
cd ./clouddev-myrepo && lzlocal push
lzlocal push --file "_Folder Name_/script.jsx"
lzlocal push --ignore-conflicts
push-concept — Push a single concept
lzlocal push-concept CONCEPT_URI [--ignore-conflicts]
| Argument | Description |
|---|---|
CONCEPT_URI |
Cloud URI of the concept to push, e.g. /myuser/myrepo/uuid/ |
--ignore-conflicts |
Overwrite cloud versions with local changes (use with care) |
cd ./clouddev-myrepo && lzlocal push-concept /clouddev/myrepo/abc123/
diff — Diff local vs cloud
lzlocal diff [--quiet]
Compares every concept of the project against the cloud, including the ones you did not edit: someone else may have changed them in the cloud since your last pull. Each difference says which side changed it. Read-only.
| Status | Meaning |
|---|---|
Modified locally |
Changed here only. push uploads it |
Modified in cloud |
Changed in the cloud only since the last pull. Nothing to push, pull brings it |
CONFLICT |
Changed in both places. push reports DETECTED_CONFLICT. The full output shows each side's changes against the last pull |
Modified |
Differs, but the concept's own JSON was edited by hand, so the side cannot be told |
Every concept is fetched from the cloud (8 at a time), so diff takes a few seconds: about 5 s for 100 concepts.
A concept that exists locally but was deleted in the cloud is counted as an error. Concepts created in the cloud since the last pull are not listed: pull fetches them.
| Argument | Description |
|---|---|
--quiet / -q |
Print only the mismatch count, not the full diff |
cd ./clouddev-myrepo && lzlocal diff
lzlocal diff --quiet
local-diff — Diff two local concept directories
lzlocal local-diff TARGET_PATH [--quiet] [--reverse]
| Argument | Description |
|---|---|
TARGET_PATH |
Local path to the target concepts directory |
--quiet / -q |
Print only the mismatch count |
--reverse / -r |
Swap source and target for the comparison |
cd ./project-dev && lzlocal local-diff ../project-qa
lzlocal local-diff ../project-qa --quiet
lzlocal local-diff ../project-qa --reverse
git-diff — Diff local vs a git repository
lzlocal git-diff GIT_PATH [--quiet] [--reverse]
| Argument | Description |
|---|---|
GIT_PATH |
Local path to the git repository |
--quiet / -q |
Print only the mismatch count |
--reverse / -r |
Swap diff direction |
cd ./clouddev-myrepo && lzlocal git-diff ./my-git-repo
lzlocal git-diff ./my-git-repo --quiet
build — Build webpack bundles from local concepts
lzlocal build [--full] [--server] [--port PORT] [--verbose]
| Argument | Description |
|---|---|
--full |
Clean the build folder and perform a complete rebuild |
--server |
Start a local resource server and watch for file changes until Ctrl-C |
--port PORT |
Port for the local resource server (default: 8080) |
--verbose |
Print each resource request served by the local server |
--full and --server are mutually exclusive.
cd ./clouddev-myrepo && lzlocal build --full
lzlocal build --server --port 9090
Advanced Commands
These commands are for full deployments and direct S3 uploads. Run them from inside the project directory (except deploy, which runs from the workspace).
deploy — Clone-or-pull then build in one shot
lzlocal deploy ROOT_URI [--api-key KEY] [--cjs-token TOKEN] [--uri URIS]
Runs from the workspace directory. Saves credentials if provided, then clones or pulls the project and builds it.
| Argument | Description |
|---|---|
ROOT_URI |
Root concept URI of the project, e.g. /clouddev/myrepo/uuid/ |
--api-key KEY |
LZ API key — saves credentials before deploying (requires --cjs-token) |
--cjs-token TOKEN |
LZ CJS token — saves credentials before deploying (requires --api-key) |
--uri URIS |
Comma-separated concept URIs to pull individually instead of a full pull; also makes the build incremental |
Behavior:
- Project directory absent →
clone+ full build - Project directory present, no
--uri→pull+ full build - Project directory present,
--urigiven →pull-conceptfor each URI + incremental build
cd ./my-workspace
lzlocal deploy /clouddev/myrepo/rootuuid/
lzlocal deploy /clouddev/myrepo/rootuuid/ --api-key abc --cjs-token xyz
lzlocal deploy /clouddev/myrepo/rootuuid/ --uri /clouddev/myrepo/uuid1/,/clouddev/myrepo/uuid2/
upload-bundle — Upload a locally built bundle to S3
lzlocal upload-bundle CONCEPT_URI [--bucket-name BUCKET]
Publishes the bundle that lzlocal build left in resource/<user>/<repo>/<uuid> for one concept, through the cloud REST API (POST /bundle). Build first: the file uploaded is whatever the last build produced, and a warning is printed if the concept's source files are newer.
| Argument | Description |
|---|---|
CONCEPT_URI |
Cloud URI of a DLL, wrapper DLL, SSJS, JS or CSS resource in this project, e.g. /myuser/myrepo/uuid/. A DLL that is a child of a wrapper has no bundle of its own — pass the wrapper's URI |
--bucket-name BUCKET |
Override the cloud's default S3 bucket (normally leave unset) |
The cloud only accepts the upload when the URI's user is the user whose credentials are used, so only a project's own concepts can be uploaded. The upload overwrites whatever is currently published for the concept. Local builds are unminified and can be tens of MB.
cd ./clouddev-myrepo && lzlocal build && lzlocal upload-bundle /clouddev/myrepo/abc123/
Windows Standalone EXEs
The EXE distribution requires no Python install. Copy both files to the same directory on %PATH%.
CLI (lzlocal.exe)
All CLI commands work identically to the pip lzlocal script:
lzlocal.exe configure --credentials
lzlocal.exe clone /clouddev/myrepo/rootuuid/
lzlocal.exe pull
lzlocal.exe push --file "folder/script.jsx"
lzlocal.exe diff --quiet
lzlocal.exe ← shows help
GUI (lzlocalw.exe)
Double-click lzlocalw.exe or run it from a terminal. It opens the LambdaZen Local project manager window where you can manage credentials, clone and pull projects, run push/diff/build, and open projects in Claude Code.
lzlocalw.exe
MCP Servers
LambdaZen exposes its tooling to AI assistants such as Claude Code through two MCP servers. Both are written into a project's .mcp.json on every clone or pull.
| Server | Transport | Runs | Use it for |
|---|---|---|---|
lambdazen-local |
stdio | Locally, bound to one project folder | Sync and build: lz_push, lz_pull, lz_diff, lz_build, lz_upload_bundle, configure_credentials, … |
lambdazen-cloud |
Streamable HTTP | In the LambdaZen cloud | Index types, schema and search, concept CRUD, eval, help, logs, control register, skills |
configure_credentials MCP tool
Available in the lambdazen-local server. Saves credentials directly from a Claude Code session without leaving the editor:
configure_credentials(user="clouddev", api_key="...", cjs_token="...")
Writes LZ_API_KEY_<USER> and LZ_CJS_TOKEN_<USER> to the workspace .env and updates .claude/settings.local.json. Restart Claude Code after calling this tool for the credentials to take effect.
Full reference — tools, resources, skills, security model, configuration, troubleshooting: docs/LambdaZen-MCP-Servers.md.
Starting the local MCP server manually
pip:
lzlocal-mcp /path/to/project
Windows EXE:
lzlocal.exe mcp /path/to/project
The local server exposes three read-only resources alongside the sync tools:
| Resource | What it returns |
|---|---|
lzlocal://project/root-uri |
Root concept URI (e.g. /user/repo/uuid/) |
lzlocal://project/local-path |
Absolute path to this project on the local filesystem |
lzlocal://user |
LambdaZen user for this project (e.g. clouddev) |
Typical Workflows
Start a new project
mkdir my-workspace && cd my-workspace
lzlocal configure --workspace
lzlocal configure --credentials --user clouddev --api-key KEY --cjs-token TOKEN
lzlocal clone /clouddev/myrepo/rootuuid/
# edit files in clouddev-myrepo/files/
lzlocal push clouddev-myrepo/
Daily sync cycle
cd ./clouddev-myrepo
lzlocal diff # check what's changed
lzlocal pull # get latest from cloud
# edit files ...
lzlocal push # upload to cloud
Refresh a single concept without pulling everything
cd ./clouddev-myrepo && lzlocal pull-concept /clouddev/myrepo/someuuid/
Compare dev and QA environments
lzlocal clone /clouddev/myrepo/rootuuid/
lzlocal clone /cloudqa/myrepo/rootuuid/
lzlocal local-diff ./clouddev-myrepo ./cloudqa-myrepo
Conflict Handling
LambdaZen Local detects conflicts in two directions:
- Pull conflicts — the cloud has a newer version of a concept you have also modified locally. Use
--ignore-conflictsto 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-conflictsto 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.
License
Proprietary — © LambdaZen Technology Corp. All rights reserved.
Metadata
Release files for lambdazen-local 0.2.9
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| lambdazen_local-0.2.9-py3-none-any.whl | Python 3 | none | any | Details for lambdazen_local-0.2.9-py3-none-any.whl |
Release files / lambdazen_local-0.2.9-py3-none-any.whl
| Download URL | lambdazen_local-0.2.9-py3-none-any.whl |
|---|---|
| Size | 86.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2d15075167352a363941694de73dd8f22653e270f4056e3ad162773a25ae3fa5
|
|
BLAKE2b-256 checksum How to use checksums |
bff46f4f2b5b0a96c54dbfdfd4626d87814e74443cb9443b7679b456b09fc968
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.9
|
Security for lambdazen-local 0.2.9
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.