lambdazen-local 0.1.2

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 to save credentials permanently to ~/.lzlocal/.env:

lzlocal configure
# Prompts: LZ_API_KEY: ...
#          LZ_CJS_TOKEN: ...

Pass values directly to skip interactive prompts:

lzlocal configure --api-key YOUR_API_KEY --cjs-token YOUR_CJS_TOKEN

Per-user / per-environment credentials

If you work with multiple LambdaZen environments (e.g. clouddev and cloudqa), you can store separate credentials keyed by the user segment of the repository URI:

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 will automatically select the right key based on the user 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
--api-key KEY	API key (prompted if omitted)
--cjs-token TOKEN	CJS token (prompted if omitted)
--user USER	User segment for per-environment credentials (e.g. clouddev)

---

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

---

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. All rights reserved.