lambdazen-local 0.1.22

LambdaZen Local — sync tool for LambdaZen concept repositories

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:

Variable	Description
LZ_API_KEY	Your LambdaZen REST API key
LZ_CJS_TOKEN	Your LambdaZen CJS token

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]

Flag	Description
--user USER	LambdaZen username / environment (e.g. clouddev, cloudqa) — prompted if omitted
--api-key KEY	API key (prompted if omitted)
--cjs-token TOKEN	CJS token (prompted if omitted)

---

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]

Argument	Description
ROOT_URI	URI of the root concept, e.g. /myuser/myrepo/rootuuid/
CONCEPTS_PATH	Local path for the new project directory (must not exist yet)
--endpoint URL	LambdaZen cloud endpoint (uses default if omitted)

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]

Flag	Description
--ignore-conflicts	Overwrite local changes with cloud versions (use with care)
--endpoint URL	LambdaZen cloud endpoint

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]

Argument	Description
CONCEPTS_PATH	Local path to the project directory
CONCEPT_URI	Cloud URI of the concept to refresh, e.g. /myuser/myrepo/uuid/

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 [--ignore-conflicts] [--endpoint URL]

Flag	Description
--ignore-conflicts	Overwrite cloud versions with local changes (use with care)
--endpoint URL	LambdaZen cloud endpoint

Examples:

lzlocal push ./my-project
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]

Flag	Description
--quiet / -q	Print only the mismatch count, not the full diff

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]

Flag	Description
--quiet / -q	Print only the mismatch count
--reverse / -r	Swap source and target for the comparison

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]

Flag	Description
--quiet / -q	Print only the mismatch count
--reverse / -r	Swap diff direction

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 Server

LambdaZen Local ships an MCP (Model Context Protocol) server that exposes LambdaZen indexes and concept operations to AI assistants such as Claude Code.

Starting the MCP server

pip:

lzlocal-mcp /path/to/concepts

Windows EXE:

LambdaZenLocal.exe mcp /path/to/concepts

MCP Tools

All tools are discoverable via tools/list and invoked via tools/call.

MCP Method	Purpose
tools/list	Discover available tools
tools/call	Invoke a tool by name with parameters

Tool	Description
list_index_types	List all available LambdaZen index types with their names and cloud URIs
get_index_schema	Fetch the Elasticsearch field schema of an index type
search_index	Execute an Elasticsearch query against an index type
get_concept_definition	Fetch the raw definition JSON of a concept
create_concept	Create a new concept under a parent folder (two-step: POST stub + PUT definition)
update_concept	Update an existing concept (full PUT replacement)
get_help_page	Retrieve embedded help documentation for a concept
get_concept_logs	Fetch execution logs for a concept (supports keyword and time range filters)
get_control_register	Fetch the control register for a user
eval_concept_value	Evaluate a concept node via the eval server
eval_concept_cast	Evaluate a concept cast to a specific ISA type
eval_concept_tree	Traverse a concept's full ISA relationship tree

MCP Resources

Resources are read-only, URI-addressed data sources. All six are resource templates and expose the following MCP protocol methods:

MCP Method	Purpose
resources/templates/list	Discover available resource templates
resources/read	Fetch resource content by providing the full URI

URI Template	Name	Description	MIME Type
def://<concept-uri>	Concept Definition	Raw definition JSON of the concept	application/json
val://<concept-uri>	Concept Value	Value of the concept from the eval server	application/json
cast://<concept-uri>::<cast-uri>	Concept Value Cast	Value cast to another concept via is-a relationships	application/json
help://<concept-uri>	Concept Help	Help documentation from the concept's Help: child	text/plain
logs://<concept-uri>	Concept Logs	All execution logs, unfiltered	application/json
controls://<user>	Concept Controls	Control register JSON for a user	application/json

Notes:

• cast:// uses :: as separator because both URIs contain forward slashes. Example: cast:///clouddev/playground/XYZ123/::/common/core/ABC/
• For filtered log access (keyword, time range), use the get_concept_logs tool instead of the logs:// resource.

---

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.