looker-sync 0.1.0__tar.gz

looker_sync-0.1.0/.claude/skills/codebase-map/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: codebase-map
+description: Where behaviour lives in looker-sync: which file owns the sync rules, the guards, the Looker API calls and the tests. Use before hunting for where something is implemented or before changing a guard.
+---
+
+# Where things live
+
+Open the one page for your area, then go straight to the file. Line numbers are a
+starting point, not an address; confirm by what the code says.
+
+<!-- BEGIN GENERATED INDEX -- edit the pages, not this block -->
+
+## Where things live
+
+One page per area of the system. Read before going looking for where
+something is implemented.
+
+| page | covers | verified |
+|---|---|---|
+| [Sync model and guards](../../../docs/architecture/sync-model-and-guards.md) | how pull, push, status and switch decide what to write, which guard refuses what, and where in looker_sync.py each lives | 2026-10-09 |
+
+<!-- END GENERATED INDEX -->
+
+The same table, browsable, is [docs/README.md](../../../docs/README.md). To add a page,
+follow the `repo-maintenance` skill, then run `scripts/gen-docs-index.sh`.

looker_sync-0.1.0/.claude/skills/repo-maintenance/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: repo-maintenance
+description: The traps, reference pages and decision records of looker-sync, indexed by symptom. Use before debugging behaviour that is wrong but not crashing, before changing the fake Looker in the tests, and whenever a debugging session cost more than an hour.
+---
+
+# Traps and reference
+
+Scan the tables below by the symptom you see, then open exactly one page. Each page
+is self-contained.
+
+<!-- BEGIN GENERATED INDEX -- edit the pages, not this block -->
+
+## Traps
+
+Failure modes that produce no error message, indexed by the symptom you
+would observe. Read before debugging behaviour that is wrong but not
+crashing.
+
+| symptom | page | area | verified |
+|---|---|---|---|
+| a changed file shows git_status action add, so it looks like a new file | [MODIFIED_FILE_SHOWS_ACTION_ADD](../../../docs/traps/MODIFIED_FILE_SHOWS_ACTION_ADD.md) | file list / git_status | 2026-10-09 |
+| unit tests pass but push fails against real Looker with HTTP 400 No such file or directory | [TESTS_PASS_BUT_PUSH_FAILS_ON_THE_REAL_LOOKER](../../../docs/traps/TESTS_PASS_BUT_PUSH_FAILS_ON_THE_REAL_LOOKER.md) | tests / fake Looker | 2026-10-09 |
+
+## Reference
+
+Simply true, and expensive to re-derive.
+
+| page | summary | verified |
+|---|---|---|
+| [Looker file and branch API behaviour (live-verified)](../../../docs/reference/looker-file-api-behaviour.md) | How the Looker API answers for new folders, directories and the shared dev checkout, as seen on a live instance | 2026-10-09 |
+
+## Decisions
+
+Why the repo is the way it is. A merged decision is immutable -- supersede
+it with a new one rather than editing it.
+
+- [The tool writes files and never touches git state](../../../docs/adr/0001-read-and-write-files-only.md)
+- [No commit command; ship on PyPI with the skill inside](../../../docs/adr/0002-no-commit-command-and-uvx-distribution.md)
+
+<!-- END GENERATED INDEX -->
+
+## Where a lesson goes
+
+Type error, then test, then a comment at the site, then a doc. A doc is the last resort.
+A fact with a symptom is a trap in `docs/traps/`; a fact that is simply true is a page in
+`docs/reference/`; a hard-to-reverse choice is a record in `docs/adr/`. Verify against
+running code, date the page `verified:`, then run `scripts/gen-docs-index.sh`.

looker_sync-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+.env
+.looker-sync/
+tmp/
+dist/
+*.egg-info/

looker_sync-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 luutuankiet
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

looker_sync-0.1.0/PKG-INFO

@@ -0,0 +1,59 @@
+Metadata-Version: 2.5
+Name: looker-sync
+Version: 0.1.0
+Summary: Pull and push LookML between a local folder and your own Looker dev workspace, with read-back verification.
+Project-URL: Homepage, https://github.com/luutuankiet/looker-sync
+Project-URL: Issues, https://github.com/luutuankiet/looker-sync/issues
+Author: luutuankiet
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,looker,lookml,sync
+Classifier: Environment :: Console
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# looker-sync
+
+Move LookML between a local folder and your own Looker dev workspace, with verification.
+Python 3 standard library only.
+
+```
+uvx looker-sync init --project <name> [--branch <b>]   # works in a blank folder
+uvx looker-sync status
+uvx looker-sync push --dry-run
+uvx looker-sync push
+uvx looker-sync skill                                  # the full guide, written for agents
+```
+
+`init` in a folder with no credentials writes an `.env` template and a `.gitignore` entry,
+then asks you to fill it in; run it again to pull.
+
+The env file holds `LOOKER_URL`, `LOOKER_CLIENT_ID` and `LOOKER_CLIENT_SECRET`, for an API
+key that belongs to **your own** Looker user.
+
+## What it guarantees
+
+- `push` writes your changes, reads every file back and compares bytes, then runs LookML
+  validation and prints `file:line  message`.
+- It refuses to overwrite a file edited in Looker since your last sync (`--force` to override).
+- `pull` never deletes local files and refuses to overwrite unpushed local work.
+- It never commits, deploys, resets or creates branches. Looker's API has no commit or push
+  endpoint, so committing stays with git and the Looker IDE.
+- A push that stops partway records what it wrote; the next push retries only the rest.
+
+## One key, one branch at a time
+
+The checked-out dev branch belongs to the Looker user, not to an API token. A second client on
+another branch is refused by a branch-mismatch guard; only `switch` moves the branch, and the
+browser IDE follows.
+
+Exit codes: 0 ok, 1 Looker or network error, 2 refused by a guard, 3 validation errors.
+
+Tests: `python3 -m unittest discover -s scripts -p 'test_looker_sync.py'`
+
+## Claude plugin
+
+The repo is also a Claude plugin: `skills/looker-sync/SKILL.md` is the one authoritative guide,
+shipped in the plugin and inside the package (`looker-sync skill` prints it).

looker_sync-0.1.0/README.md

@@ -0,0 +1,43 @@
+# looker-sync
+
+Move LookML between a local folder and your own Looker dev workspace, with verification.
+Python 3 standard library only.
+
+```
+uvx looker-sync init --project <name> [--branch <b>]   # works in a blank folder
+uvx looker-sync status
+uvx looker-sync push --dry-run
+uvx looker-sync push
+uvx looker-sync skill                                  # the full guide, written for agents
+```
+
+`init` in a folder with no credentials writes an `.env` template and a `.gitignore` entry,
+then asks you to fill it in; run it again to pull.
+
+The env file holds `LOOKER_URL`, `LOOKER_CLIENT_ID` and `LOOKER_CLIENT_SECRET`, for an API
+key that belongs to **your own** Looker user.
+
+## What it guarantees
+
+- `push` writes your changes, reads every file back and compares bytes, then runs LookML
+  validation and prints `file:line  message`.
+- It refuses to overwrite a file edited in Looker since your last sync (`--force` to override).
+- `pull` never deletes local files and refuses to overwrite unpushed local work.
+- It never commits, deploys, resets or creates branches. Looker's API has no commit or push
+  endpoint, so committing stays with git and the Looker IDE.
+- A push that stops partway records what it wrote; the next push retries only the rest.
+
+## One key, one branch at a time
+
+The checked-out dev branch belongs to the Looker user, not to an API token. A second client on
+another branch is refused by a branch-mismatch guard; only `switch` moves the branch, and the
+browser IDE follows.
+
+Exit codes: 0 ok, 1 Looker or network error, 2 refused by a guard, 3 validation errors.
+
+Tests: `python3 -m unittest discover -s scripts -p 'test_looker_sync.py'`
+
+## Claude plugin
+
+The repo is also a Claude plugin: `skills/looker-sync/SKILL.md` is the one authoritative guide,
+shipped in the plugin and inside the package (`looker-sync skill` prints it).

looker_sync-0.1.0/docs/README.md

@@ -0,0 +1,47 @@
+# Documentation
+
+Every page here is written for a maintainer six months from now who opened
+exactly this file from a search result and has nothing else loaded.
+
+This index is generated. Run `scripts/gen-docs-index.sh` after adding or
+renaming a page; `--check` fails if it is stale.
+
+<!-- BEGIN GENERATED INDEX -- edit the pages, not this block -->
+
+## Where things live
+
+One page per area of the system. Read before going looking for where
+something is implemented.
+
+| page | covers | verified |
+|---|---|---|
+| [Sync model and guards](architecture/sync-model-and-guards.md) | how pull, push, status and switch decide what to write, which guard refuses what, and where in looker_sync.py each lives | 2026-10-09 |
+
+## Traps
+
+Failure modes that produce no error message, indexed by the symptom you
+would observe. Read before debugging behaviour that is wrong but not
+crashing.
+
+| symptom | page | area | verified |
+|---|---|---|---|
+| a changed file shows git_status action add, so it looks like a new file | [MODIFIED_FILE_SHOWS_ACTION_ADD](traps/MODIFIED_FILE_SHOWS_ACTION_ADD.md) | file list / git_status | 2026-10-09 |
+| unit tests pass but push fails against real Looker with HTTP 400 No such file or directory | [TESTS_PASS_BUT_PUSH_FAILS_ON_THE_REAL_LOOKER](traps/TESTS_PASS_BUT_PUSH_FAILS_ON_THE_REAL_LOOKER.md) | tests / fake Looker | 2026-10-09 |
+
+## Reference
+
+Simply true, and expensive to re-derive.
+
+| page | summary | verified |
+|---|---|---|
+| [Looker file and branch API behaviour (live-verified)](reference/looker-file-api-behaviour.md) | How the Looker API answers for new folders, directories and the shared dev checkout, as seen on a live instance | 2026-10-09 |
+
+## Decisions
+
+Why the repo is the way it is. A merged decision is immutable -- supersede
+it with a new one rather than editing it.
+
+- [The tool writes files and never touches git state](adr/0001-read-and-write-files-only.md)
+- [No commit command; ship on PyPI with the skill inside](adr/0002-no-commit-command-and-uvx-distribution.md)
+
+<!-- END GENERATED INDEX -->

looker_sync-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "looker-sync"
+version = "0.1.0"
+description = "Pull and push LookML between a local folder and your own Looker dev workspace, with read-back verification."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+authors = [{ name = "luutuankiet" }]
+keywords = ["looker", "lookml", "sync", "cli"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Operating System :: OS Independent",
+  "Environment :: Console",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/luutuankiet/looker-sync"
+Issues = "https://github.com/luutuankiet/looker-sync/issues"
+
+[project.scripts]
+looker-sync = "looker_sync.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/looker_sync"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"skills/looker-sync" = "looker_sync/_skills_data/looker-sync"
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "skills", "README.md", "LICENSE", "pyproject.toml"]

looker_sync-0.1.0/skills/looker-sync/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: looker-sync
+description: Move LookML between a local folder and your own Looker dev workspace with the looker-sync CLI (pull, status, push with byte-for-byte read-back and validation, switch). Use before editing any LookML that must reach Looker, before validating a Looker project, when mounting a Looker project into a new folder, and when Looker and the local files might disagree.
+---
+
+# looker-sync
+
+`looker-sync` is the only path from local LookML to Looker. It talks to the Looker API with
+your own key. It never commits, deploys, resets or creates branches: Looker's API has no
+commit or push endpoint, so committing stays with git, and the rest stay clicks in the Looker
+IDE. Agents cannot commit LookML through this tool.
+
+```
+uvx looker-sync [-C <project folder>] [--env-file <path>] <command>
+```
+
+`-C` defaults to the current folder. The env file holds `LOOKER_URL`, `LOOKER_CLIENT_ID`
+and `LOOKER_CLIENT_SECRET`. It is found as `--env-file`, then `LOOKER_SYNC_ENV`, then the
+`env_file` in `.looker-sync/config.json`, then `.env` in the project folder. Never open it
+yourself. `looker-sync --help` is the short reference; `looker-sync skill` prints this guide.
+
+## The loop
+
+1. `status`: what differs. Nothing is written.
+2. Edit the files with your normal tools.
+3. `push --dry-run`, then `push`. Push writes local changes, reads every file back, compares
+   bytes, then runs LookML validation and prints errors as `file:line  message`.
+4. Fix, push again, until exit 0.
+
+| exit | meaning | what to do |
+|---|---|---|
+| 0 | ok | carry on |
+| 1 | Looker or network error, or a read-back mismatch | read the message; do not retry blindly |
+| 2 | refused by a guard | read the reason; it names the files |
+| 3 | pushed and verified, but validation has errors | fix them; check whether they were there before your push |
+
+**Read the first line of every run.** It names the Looker user, project, mode and branch.
+If the user is not the developer you are working for, stop: a key for another user writes
+to that user's dev workspace, which the developer never sees.
+
+## Guards, and what each refusal means
+
+- **Branch mismatch.** Looker's dev workspace is on another branch than the folder's config.
+  Someone switched in the IDE. Stop and tell the user; only `switch` moves branches.
+- **Changed in Looker since the last sync** (push). Someone edited in the Looker IDE. Run
+  `pull` to take their copy if you have not touched that file; otherwise report it. Use
+  `push --force` only when the user has said local wins.
+- **Pull would overwrite unpushed local changes.** Push your work first. `pull --force`
+  throws it away.
+- **Push refused in prod mode.** Production is read-only by design.
+- **One key, one branch at a time.** The checked-out branch belongs to the Looker user, not
+  to a token: a second client or folder on another branch hits the branch-mismatch guard, and
+  only `switch` moves everyone. Do not run two branches in parallel on one key.
+
+## Rules
+
+- A new folder is created for you. A push writes new files before changed ones and records
+  each file as soon as it is written and read back. If it stops partway it prints `written:`
+  and `not written:`; just push again, no `--force` is needed.
+- `--force` and `--delete` need a stated reason in your reply. Files that exist only in
+  Looker are listed by every push and deleted only with `--delete`.
+- `pull` never deletes local files, and keeps a file you deleted locally deleted.
+- `switch` moves the user's whole dev workspace, browser IDE included. Leave it to the user
+  unless they asked. It refuses while any Looker file is uncommitted, and without a terminal
+  it needs `--yes` plus `--local-changes push|backup|cancel` when local work is unpushed.
+  Backups land in `.looker-sync/backups/<branch>-<timestamp>/`.
+- Only `*.lkml` and `*.dashboard.lookml` sync by default (`include`/`exclude` in the
+  config). `.env`, skills, editor settings and `.looker-sync/` never reach Looker.
+- The Looker MCP write tools are not an alternative: they run in production mode under a
+  separate login and cannot see dev files. MCP read and query tools are fine.
+
+## Mounting a project, including from a blank folder
+
+```
+mkdir my-project && cd my-project
+uvx looker-sync init --project <name> [--branch <b>]
+```
+
+In a folder with no credentials, `init` writes a `.env` template (owner-only permissions),
+adds `.env` and `.looker-sync/` to `.gitignore`, and exits with code 2 telling you what to
+fill in. The user fills `LOOKER_URL`, `LOOKER_CLIENT_ID` and `LOOKER_CLIENT_SECRET`; run the
+same `init` command again and it writes `.looker-sync/config.json` and pulls. It never
+overwrites a filled `.env` or an existing config. On a terminal it asks for the project and
+whether to pull; `--no-pull` writes metadata only.
+
+`init` refuses if the Looker dev workspace is on a different branch than `--branch` (it
+never switches), and its first pull refuses to overwrite local files that differ from
+Looker (`--force` takes Looker's copy). Mount into an empty folder and compare by hand when
+in doubt: a folder kept by another sync tool can be stale.
+
+## Committing
+
+`looker-sync` does not commit. `status` prints how many commits the dev branch is ahead of
+and behind its remote; commit and push with git from the Looker IDE or a clone of the
+remote. Looker has no commit or push endpoint in its API, and the official Looker VS Code
+extension (1.0.0) does not use one either: it commits through local git.
+
+## Tests
+
+From a source checkout, `python3 -m unittest discover -s scripts -p 'test_looker_sync.py'`
+runs the CLI against a fake Looker. Run it after any change to the tool.

looker_sync-0.1.0/src/looker_sync/__main__.py

@@ -0,0 +1,4 @@
+from looker_sync.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

looker_sync-0.1.0/src/looker_sync/cli.py

@@ -0,0 +1,740 @@
+#!/usr/bin/env python3
+"""looker-sync: pull and push LookML between a local folder and a Looker dev workspace.
+
+Talks to the Looker REST API (4.0) directly with the user's own API key. Standard library
+only. Never commits, deploys, resets or creates branches: Looker's API has no commit or push
+endpoint, so those stay with git and the Looker IDE.
+
+    looker-sync [-C PROJECT_DIR] [--env-file PATH] COMMAND ...
+
+    init    [--project P] [--mode dev|prod] [--branch B]  set up a folder, then a first pull
+    pull    [--force] [--dry-run]                         copy Looker files to disk
+    status                                                show what differs on each side
+    push    [--force] [--delete] [--dry-run]              write local edits, read back, validate
+    switch  (--branch B | --mode dev|prod) [--local-changes push|backup|cancel] [--yes]
+    skill   [--path]                                      print the full usage guide for agents
+
+Metadata lives in PROJECT_DIR/.looker-sync/ (config.json, state.json, backups/). Credentials
+come only from the env file: LOOKER_URL, LOOKER_CLIENT_ID, LOOKER_CLIENT_SECRET.
+
+Exit codes: 0 ok, 1 Looker or network error, 2 refused by a guard, 3 validation errors.
+"""
+import argparse
+import datetime
+import hashlib
+import json
+import os
+import re
+import shutil
+import sys
+import urllib.error
+import urllib.parse
+import urllib.request
+
+META_DIR = '.looker-sync'
+DEFAULT_INCLUDE = ['**/*.lkml', '**/*.dashboard.lookml']
+OK, LOOKER_ERROR, REFUSED, INVALID = 0, 1, 2, 3
+WORKSPACE = {'dev': 'dev', 'prod': 'production'}
+
+
+class LookerError(Exception):
+    pass
+
+
+class Refused(Exception):
+    pass
+
+
+def out(msg=''):
+    print(msg, flush=True)
+
+
+def sha(data):
+    return None if data is None else hashlib.sha256(data).hexdigest()
+
+
+# ---------------------------------------------------------------- env and API
+
+def load_env(path):
+    if not os.path.isfile(path):
+        raise LookerError(f'env file not found: {path}')
+    env = {}
+    with open(path) as f:
+        for line in f:
+            line = line.strip()
+            if line.startswith('export '):
+                line = line[len('export '):]
+            if not line or line.startswith('#') or '=' not in line:
+                continue
+            k, v = line.split('=', 1)
+            env[k.strip()] = v.strip().strip('"').strip("'")
+    missing = [k for k in ('LOOKER_URL', 'LOOKER_CLIENT_ID', 'LOOKER_CLIENT_SECRET') if not env.get(k)]
+    if missing:
+        raise LookerError(f'env file {path} lacks {", ".join(missing)}')
+    return env
+
+
+class Looker:
+    """One login per command run. The token lives in memory only."""
+
+    def __init__(self, env):
+        url = env['LOOKER_URL'].rstrip('/')
+        self.base = url if url.endswith('/api/4.0') else url + '/api/4.0'
+        body = urllib.parse.urlencode({'client_id': env['LOOKER_CLIENT_ID'],
+                                       'client_secret': env['LOOKER_CLIENT_SECRET']}).encode()
+        status, payload = self._send('POST', '/login', body, {'Content-Type': 'application/x-www-form-urlencoded'})
+        if status != 200:
+            # The request carried the secret; the response never does, but keep it terse anyway.
+            raise LookerError(f'login failed: HTTP {status}')
+        self.token = json.loads(payload)['access_token']
+
+    def _send(self, method, path, data=None, headers=None):
+        req = urllib.request.Request(self.base + path, data=data, method=method, headers=headers or {})
+        try:
+            with urllib.request.urlopen(req, timeout=120) as r:
+                return r.status, r.read()
+        except urllib.error.HTTPError as e:
+            return e.code, e.read()
+        except (urllib.error.URLError, OSError) as e:
+            raise LookerError(f'{method} {path}: {e}')
+
+    def try_call(self, method, path, query=None, body=None, raw=False):
+        if query:
+            path += '?' + urllib.parse.urlencode(query)
+        headers = {'Authorization': 'token ' + self.token}
+        data = None
+        if body is not None:
+            data = json.dumps(body).encode()
+            headers['Content-Type'] = 'application/json'
+        status, payload = self._send(method, path, data, headers)
+        if status >= 400:
+            try:
+                msg = json.loads(payload).get('message') or payload.decode(errors='replace')
+            except (ValueError, AttributeError):
+                msg = payload.decode(errors='replace')
+            return status, msg[:300]
+        if raw:
+            return status, payload
+        return status, json.loads(payload) if payload else None
+
+    def call(self, method, path, query=None, body=None, raw=False):
+        status, payload = self.try_call(method, path, query, body, raw)
+        if status >= 400:
+            raise LookerError(f'{method} {path.split("?")[0]} -> HTTP {status}: {payload}')
+        return payload
+
+
+# ---------------------------------------------------------------- project folder
+
+def glob_regex(pattern):
+    i, rx = 0, ''
+    while i < len(pattern):
+        if pattern.startswith('**/', i):
+            rx, i = rx + '(?:.*/)?', i + 3
+        elif pattern.startswith('**', i):
+            rx, i = rx + '.*', i + 2
+        elif pattern[i] == '*':
+            rx, i = rx + '[^/]*', i + 1
+        elif pattern[i] == '?':
+            rx, i = rx + '[^/]', i + 1
+        else:
+            rx, i = rx + re.escape(pattern[i]), i + 1
+    return re.compile(rx + r'\Z')
+
+
+class Project:
+    def __init__(self, root):
+        self.root = os.path.abspath(root)
+        self.meta = os.path.join(self.root, META_DIR)
+        self.config_path = os.path.join(self.meta, 'config.json')
+        self.state_path = os.path.join(self.meta, 'state.json')
+        self.config = self._read(self.config_path)
+        self.state = self._read(self.state_path) or {'files': {}}
+
+    @staticmethod
+    def _read(path):
+        if not os.path.isfile(path):
+            return None
+        with open(path) as f:
+            return json.load(f)
+
+    def _write(self, path, data):
+        os.makedirs(self.meta, exist_ok=True)
+        tmp = path + '.tmp'
+        with open(tmp, 'w') as f:
+            json.dump(data, f, indent=2, sort_keys=True)
+            f.write('\n')
+        os.replace(tmp, path)
+
+    def save_config(self):
+        self._write(self.config_path, self.config)
+
+    def save_state(self):
+        self._write(self.state_path, self.state)
+
+    def require_config(self):
+        if not self.config:
+            raise Refused(f'no {META_DIR}/config.json in {self.root}; run init first')
+        return self.config
+
+    def synced(self, path):
+        """True if the path is in the sync set. The metadata folder never is."""
+        if path.split('/')[0] == META_DIR:
+            return False
+        cfg = self.config or {}
+        inc = [glob_regex(p) for p in cfg.get('include', DEFAULT_INCLUDE)]
+        exc = [glob_regex(p) for p in cfg.get('exclude', [])]
+        return any(r.match(path) for r in inc) and not any(r.match(path) for r in exc)
+
+    def local_files(self):
+        found = {}
+        for dirpath, dirnames, filenames in os.walk(self.root):
+            rel_dir = os.path.relpath(dirpath, self.root)
+            if rel_dir == '.':
+                dirnames[:] = [d for d in dirnames if d != META_DIR]
+            for name in filenames:
+                rel = name if rel_dir == '.' else f'{rel_dir}/{name}'.replace(os.sep, '/')
+                if self.synced(rel):
+                    with open(os.path.join(dirpath, name), 'rb') as f:
+                        found[rel] = f.read()
+        return found
+
+    def write_local(self, path, data):
+        full = os.path.join(self.root, *path.split('/'))
+        os.makedirs(os.path.dirname(full), exist_ok=True)
+        with open(full, 'wb') as f:
+            f.write(data)
+
+    def env_path(self, flag):
+        flag = flag or os.environ.get('LOOKER_SYNC_ENV')
+        if flag:
+            return flag
+        if self.config and self.config.get('env_file'):
+            return os.path.join(self.root, self.config['env_file'])
+        return os.path.join(self.root, '.env')
+
+
+# ---------------------------------------------------------------- session
+
+class Session:
+    """Log in, set the workspace from the config mode, confirm it, print who and where."""
+
+    def __init__(self, proj, env_flag, mode, project, branch, check_branch=True):
+        self.proj, self.project, self.mode = proj, project, mode
+        self.L = Looker(load_env(proj.env_path(env_flag)))
+        self.set_mode(mode)
+        u = self.L.call('GET', '/user')
+        self.user = f'{u.get("display_name")} <{u.get("email")}> [id {u.get("id")}]'
+        self.branch = self.current_branch()
+        shown = self.branch if mode == 'dev' else f'{self.branch} (production)'
+        out(f'looker-sync: as {self.user} · project {project} · mode {mode} · branch {shown}')
+        if mode == 'dev' and check_branch and branch != self.branch:
+            raise Refused(f'branch mismatch: config says {branch!r}, Looker dev workspace is on '
+                          f'{self.branch!r}. Run switch, or check out {branch!r} in the Looker IDE.')
+
+    def set_mode(self, mode):
+        want = WORKSPACE[mode]
+        self.L.call('PATCH', '/session', body={'workspace_id': want})
+        got = (self.L.call('GET', '/session') or {}).get('workspace_id')
+        if got != want:
+            raise LookerError(f'session workspace is {got!r} after asking for {want!r}')
+        self.mode = mode
+
+    def current_branch(self):
+        status, b = self.L.try_call('GET', f'/projects/{self.project}/git_branch')
+        if status >= 400:
+            if self.mode == 'dev':
+                raise LookerError(f'GET git_branch -> HTTP {status}: {b}')
+            return None
+        self.branch_info = b
+        return b.get('name')
+
+    def file_list(self):
+        return self.L.call('GET', f'/projects/{self.project}/files') or []
+
+    def remote_files(self):
+        """{path: bytes} for every Looker file in the sync set."""
+        files = {}
+        for f in self.file_list():
+            if self.proj.synced(f['path']):
+                files[f['path']] = self.read(f['path'])
+        return files
+
+    def read(self, path):
+        return self.L.call('GET', f'/projects/{self.project}/file/content', {'file_path': path}, raw=True)
+
+    def write(self, path, data, exists):
+        body = {'path': path, 'content': data.decode('utf-8')}
+        base = f'/projects/{self.project}/files'
+        if exists:
+            return self.L.call('PUT', base, body=body)
+        status, msg = self.L.try_call('POST', base, body=body)
+        # Looker answers 400 'No such file or directory' for a missing folder; older/other builds 404
+        missing_folder = status == 404 or (status == 400 and 'No such file or directory' in str(msg))
+        if missing_folder and '/' in path:
+            parts = path.split('/')[:-1]
+            for i in range(1, len(parts) + 1):
+                self.L.try_call('POST', f'/projects/{self.project}/directories', body={'path': '/'.join(parts[:i])})
+            status, msg = self.L.try_call('POST', base, body=body)
+        if status >= 400:
+            raise LookerError(f'POST {base} {path} -> HTTP {status}: {msg}')
+
+    def delete(self, path):
+        self.L.call('DELETE', f'/projects/{self.project}/files', {'file_path': path})
+
+    def validate(self):
+        res = self.L.call('POST', f'/projects/{self.project}/validate') or {}
+        errors = 0
+        for e in res.get('errors') or []:
+            sev = e.get('severity') or 'error'
+            where = e.get('source_file') or e.get('file_path') or f'(no file; model {e.get("model_id") or "?"})'
+            if e.get('line_number') or e.get('line'):
+                where += f':{e.get("line_number") or e.get("line")}'
+            out(f'  {sev:7} {where}  {e.get("message")}')
+            if sev in ('error', 'fatal'):
+                errors += 1
+        out(f'validation: {errors} error(s)' if errors else 'validation: no errors')
+        return errors
+
+    def uncommitted(self):
+        return [(f['path'], f['git_status'].get('text') or f['git_status'].get('action'))
+                for f in self.file_list() if f.get('git_status')]
+
+
+def open_session(proj, args, check_branch=True):
+    cfg = proj.require_config()
+    return Session(proj, args.env_file, cfg['mode'], cfg['project'], cfg.get('branch'), check_branch)
+
+
+# ---------------------------------------------------------------- sync plan
+
+KIND_TEXT = {
+    'local-new': 'only local (push creates it)',
+    'local-modified': 'changed locally (push writes it)',
+    'local-deleted': 'deleted locally (push --delete removes it from Looker)',
+    'remote-new': 'only in Looker (pull writes it; push --delete removes it)',
+    'remote-modified': 'changed in Looker since last sync (pull writes it)',
+    'remote-deleted': 'deleted in Looker since last sync (pull keeps the local copy)',
+    'conflict': 'changed on both sides',
+}
+REMOTE_CHANGED = ('remote-modified', 'remote-deleted', 'conflict')
+
+
+def plan(local, remote, known):
+    """{path: kind} for every path that differs. known = {path: sha at last sync}."""
+    kinds = {}
+    for path in sorted(set(local) | set(remote) | set(known)):
+        lh, rh, s = sha(local.get(path)), sha(remote.get(path)), known.get(path)
+        if lh == rh:
+            continue
+        lc, rc = lh != s, rh != s
+        if s is None:
+            kinds[path] = 'remote-new' if lh is None else 'local-new' if rh is None else 'conflict'
+        elif lc and rc:
+            kinds[path] = 'conflict'
+        elif lc:
+            kinds[path] = 'local-deleted' if lh is None else 'local-modified'
+        else:
+            kinds[path] = 'remote-deleted' if rh is None else 'remote-modified'
+    return kinds
+
+
+def show(kinds, header):
+    if not kinds:
+        out(f'{header}: nothing differs')
+        return
+    out(f'{header}:')
+    for kind in KIND_TEXT:
+        paths = [p for p, k in kinds.items() if k == kind]
+        if paths:
+            out(f'  {KIND_TEXT[kind]}:')
+            for p in paths:
+                out(f'    {p}')
+
+
+def record(proj, sess, updates, drops=()):
+    files = proj.state.setdefault('files', {})
+    files.update(updates)
+    for p in drops:
+        files.pop(p, None)
+    proj.state.update({'mode': sess.mode, 'branch': sess.branch if sess.mode == 'dev' else None,
+                       'production_branch': sess.branch if sess.mode == 'prod' else None,
+                       'user': sess.user,
+                       'synced_at': datetime.datetime.now(datetime.timezone.utc).isoformat(timespec='seconds')})
+    proj.save_state()
+
+
+def in_sync(local, remote):
+    return {p: sha(d) for p, d in remote.items() if local.get(p) == d}
+
+
+# ---------------------------------------------------------------- commands
+
+def do_pull(proj, sess, force=False, dry_run=False):
+    local, remote = proj.local_files(), sess.remote_files()
+    kinds = plan(local, remote, proj.state.get('files', {}))
+    blocked = [p for p, k in kinds.items() if k == 'conflict' and p in remote]
+    writes = [p for p, k in kinds.items() if k in ('remote-new', 'remote-modified')]
+    show(kinds, 'pull plan')
+    if blocked and not force:
+        raise Refused('pull would overwrite unpushed local changes in: ' + ', '.join(blocked)
+                      + '. Push them, back them up, or pull --force to take Looker\'s copy.')
+    writes += blocked
+    if dry_run:
+        out(f'dry run: would write {len(writes)} file(s); nothing written')
+        return OK
+    for p in writes:
+        proj.write_local(p, remote[p])
+        out(f'  wrote {p}')
+    updates = in_sync(local, remote)
+    updates.update({p: sha(remote[p]) for p in writes})
+    record(proj, sess, updates)
+    out(f'pull: wrote {len(writes)} file(s)')
+    return OK
+
+
+ENV_TEMPLATE = """# Looker API credentials for looker-sync. Never commit this file.
+# Create an API key in Looker: Admin > Users > your user > Edit Keys.
+LOOKER_URL=https://<your-instance>.looker.com
+LOOKER_CLIENT_ID=
+LOOKER_CLIENT_SECRET=
+"""
+
+
+def interactive():
+    return sys.stdin.isatty() and sys.stdout.isatty()
+
+
+def ask(prompt, default=None):
+    shown = f'{prompt} [{default}]: ' if default else f'{prompt}: '
+    return input(shown).strip() or default
+
+
+def ensure_gitignore(root, lines):
+    path = os.path.join(root, '.gitignore')
+    have = open(path).read().splitlines() if os.path.isfile(path) else []
+    add = [l for l in lines if l not in have]
+    if add:
+        with open(path, 'a') as f:
+            if have and not open(path).read().endswith('\n'):
+                f.write('\n')
+            f.write('\n'.join(add) + '\n')
+        out(f'added {", ".join(add)} to .gitignore')
+
+
+def env_ready(path):
+    """True when the env file exists and holds real values, not the template blanks."""
+    if not os.path.isfile(path):
+        return False
+    try:
+        load_env(path)
+    except LookerError:
+        return False
+    with open(path) as f:
+        return '<your-instance>' not in f.read()
+
+
+def cmd_init(proj, args):
+    resume = bool(proj.config) and not proj.state.get('synced_at')
+    if proj.config and not resume:
+        raise Refused(f'{proj.config_path} already exists; edit it or remove it first')
+    project = (proj.config or {}).get('project') or args.project
+    if not project and interactive():
+        project = ask('Looker project id (the name in the Looker IDE)')
+    if not project:
+        raise Refused('init needs --project <looker project id>')
+    env_path = proj.env_path(args.env_file)
+    if not env_ready(env_path):
+        if not os.path.isfile(env_path):
+            os.makedirs(os.path.dirname(os.path.abspath(env_path)), exist_ok=True)
+            fd = os.open(env_path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+            with os.fdopen(fd, 'w') as f:
+                f.write(ENV_TEMPLATE)
+            out(f'wrote {env_path} (a template; owner-only permissions)')
+        if os.path.abspath(env_path).startswith(proj.root + os.sep):
+            ensure_gitignore(proj.root, [os.path.relpath(env_path, proj.root), META_DIR + '/'])
+        raise Refused(f'fill in LOOKER_URL, LOOKER_CLIENT_ID and LOOKER_CLIENT_SECRET in {env_path}, '
+                      f'then run: looker-sync init --project {project}')
+    mode = (proj.config or {}).get('mode') or args.mode
+    sess = Session(proj, args.env_file, mode, project, args.branch, check_branch=False)
+    branch = (proj.config or {}).get('branch') or args.branch or sess.branch
+    if mode == 'dev' and branch != sess.branch:
+        raise Refused(f'Looker dev workspace is on {sess.branch!r}, not {branch!r}. init never '
+                      'switches; check out the branch in the Looker IDE first, or omit --branch.')
+    if not proj.config:
+        env_flag = args.env_file
+        env_rel = os.path.relpath(os.path.abspath(env_flag), proj.root) if env_flag else '.env'
+        proj.config = {'project': project, 'mode': mode, 'branch': branch if mode == 'dev' else None,
+                       'env_file': env_rel, 'include': args.include or DEFAULT_INCLUDE,
+                       'exclude': args.exclude or []}
+        proj.save_config()
+        out(f'wrote {os.path.relpath(proj.config_path, proj.root)}')
+    ensure_gitignore(proj.root, [META_DIR + '/'])
+    if args.no_pull:
+        out('skipped the first pull; run: looker-sync pull')
+        return OK
+    if interactive() and (ask('Pull the project files into this folder now? (y/n)', 'y') or 'y').lower() != 'y':
+        out('skipped the first pull; run: looker-sync pull')
+        return OK
+    return do_pull(proj, sess, args.force)
+
+
+def cmd_pull(proj, args):
+    return do_pull(proj, open_session(proj, args), args.force, args.dry_run)
+
+
+def cmd_status(proj, args):
+    sess = open_session(proj, args)
+    kinds = plan(proj.local_files(), sess.remote_files(), proj.state.get('files', {}))
+    show(kinds, 'status')
+    info = getattr(sess, 'branch_info', None) or {}
+    if sess.mode == 'dev' and info.get('ahead_count') is not None:
+        out(f'git: {info.get("ahead_count")} commit(s) ahead of and {info.get("behind_count")} behind '
+            f'{info.get("remote_ref") or "the remote"}; commit and push with git, not looker-sync')
+    if proj.state.get('synced_at'):
+        out(f'last sync: {proj.state["synced_at"]} by {proj.state.get("user")}')
+    return OK
+
+
+def do_push(proj, sess, force=False, delete=False, dry_run=False):
+    if sess.mode != 'dev':
+        raise Refused('push is refused in prod mode; switch --mode dev first')
+    local, remote = proj.local_files(), sess.remote_files()
+    kinds = plan(local, remote, proj.state.get('files', {}))
+    show(kinds, 'push plan')
+    guarded = [p for p, k in kinds.items() if k in REMOTE_CHANGED]
+    if guarded and not force:
+        raise Refused('changed in Looker since the last sync: ' + ', '.join(guarded)
+                      + '. Pull first, or push --force to overwrite with the local copy.')
+    writes = [p for p, k in kinds.items() if p in local and k in ('local-new', 'local-modified', 'conflict', 'remote-deleted')]
+    deletes = [p for p, k in kinds.items() if p not in local and k in ('remote-new', 'local-deleted', 'conflict')]
+    skipped = [p for p, k in kinds.items() if k == 'remote-modified']
+    if skipped:
+        out('left alone, unchanged locally (pull to get Looker\'s copy): ' + ', '.join(skipped))
+    if deletes and not delete:
+        out('not deleted without --delete: ' + ', '.join(deletes))
+        deletes = []
+    if dry_run:
+        out(f'dry run: would write {len(writes)} and delete {len(deletes)} file(s); nothing written')
+        return OK
+    # New files first: a changed file (an include:) is more likely to reference a new one than the
+    # reverse, so stopping halfway leaves Looker valid. Each write is read back and recorded at once,
+    # so a failure later in the run never makes the next push see our own writes as Looker edits.
+    writes.sort(key=lambda p: p in remote)
+    done, verified, bad = [], {}, []
+    try:
+        for p in writes:
+            sess.write(p, local[p], exists=p in remote)
+            done.append(p)
+            out(f'  wrote {p}')
+            back = sess.read(p)
+            if back == local[p]:
+                verified[p] = sha(back)
+                record(proj, sess, {p: verified[p]})
+            else:
+                bad.append(p)
+        for p in deletes:
+            sess.delete(p)
+            done.append(p)
+            out(f'  deleted {p}')
+            record(proj, sess, {}, drops=[p])
+    except LookerError:
+        out('push stopped partway. Recorded as in sync, so the next push retries only the rest.')
+        out('  written: ' + (', '.join(done) or '(none)'))
+        out('  not written: ' + (', '.join(p for p in writes + deletes if p not in done) or '(none)'))
+        raise
+    updates = in_sync(local, remote)
+    updates.update(verified)
+    record(proj, sess, updates, drops=deletes)
+    out(f'read-back: {len(verified)}/{len(writes)} byte-equal')
+    for p in bad:
+        out(f'  MISMATCH {p}: Looker holds different bytes than were sent')
+    errors = sess.validate() if (writes or deletes) else 0
+    if bad:
+        return LOOKER_ERROR
+    return INVALID if errors else OK
+
+
+def cmd_push(proj, args):
+    return do_push(proj, open_session(proj, args), args.force, args.delete, args.dry_run)
+
+
+def ask(question, choices):
+    while True:
+        ans = input(f'{question} ').strip().lower()
+        for c in choices:
+            if ans and c.startswith(ans):
+                return c
+
+
+def cmd_switch(proj, args):
+    cfg = proj.require_config()
+    interactive = sys.stdin.isatty()
+    sess = open_session(proj, args, check_branch=False)
+    target_mode = 'dev' if args.branch else args.mode
+    if target_mode == 'dev' and sess.mode != 'dev':
+        sess.set_mode('dev')
+        sess.branch = sess.current_branch()
+    target_branch = args.branch or (sess.branch if target_mode == 'dev' else None)
+    if target_mode == cfg['mode'] and (target_mode == 'prod' or target_branch == cfg.get('branch') == sess.branch):
+        out(f'already on {target_mode} {target_branch or ""}; nothing to switch')
+        return OK
+    if args.branch:
+        names = [b.get('name') for b in sess.L.call('GET', f'/projects/{cfg["project"]}/git_branches') or []]
+        if args.branch not in names:
+            raise Refused(f'branch {args.branch!r} does not exist in Looker; switch never creates branches')
+
+    def remote_guard():
+        if cfg['mode'] != 'dev':
+            return
+        dirty = sess.uncommitted()
+        if dirty:
+            raise Refused('Looker dev workspace has uncommitted changes:\n'
+                          + '\n'.join(f'    {p}  ({t})' for p, t in dirty)
+                          + '\n  Commit or revert them in the Looker IDE, then run switch again.')
+
+    remote_guard()
+    local = proj.local_files()
+    known = proj.state.get('files', {})
+    changed = [p for p in sorted(set(local) | set(known)) if sha(local.get(p)) != known.get(p)]
+    if changed:
+        out('local changes not pushed to Looker:')
+        for p in changed:
+            out(f'    {p}')
+        choice = args.local_changes
+        if not choice and interactive:
+            choice = ask('[p]ush them first, [b]ack up and discard, or [c]ancel?', ['push', 'backup', 'cancel'])
+        if not choice:
+            raise Refused('no terminal to ask; pass --local-changes push|backup|cancel')
+        if choice == 'cancel':
+            raise Refused('cancelled; nothing changed')
+        if choice == 'push':
+            if cfg['mode'] != 'dev':
+                raise Refused('cannot push from prod mode; use --local-changes backup or cancel')
+            do_push(proj, sess)
+            remote_guard()
+        if choice == 'backup':
+            stamp = datetime.datetime.now().strftime('%Y%m%dT%H%M%S')
+            label = (cfg.get('branch') if cfg['mode'] == 'dev' else 'production') or 'unknown'
+            dest = os.path.join(proj.meta, 'backups', f'{re.sub(r"[^A-Za-z0-9._-]", "_", label)}-{stamp}')
+            for p, data in local.items():
+                full = os.path.join(dest, *p.split('/'))
+                os.makedirs(os.path.dirname(full), exist_ok=True)
+                with open(full, 'wb') as f:
+                    f.write(data)
+            out(f'backed up {len(local)} local file(s) to {os.path.relpath(dest, proj.root)}')
+
+    where = f'branch {target_branch}' if target_mode == 'dev' else 'production'
+    if not args.yes:
+        if not interactive:
+            raise Refused(f'no terminal to confirm; pass --yes to switch to {where}')
+        if ask(f'Switch to {where}? This moves your Looker IDE too. [y/N]', ['yes', 'no']) != 'yes':
+            raise Refused('cancelled; nothing changed')
+
+    if target_mode == 'dev':
+        if sess.branch != target_branch:
+            sess.L.call('PUT', f'/projects/{cfg["project"]}/git_branch', body={'name': target_branch})
+            now = sess.current_branch()
+            if now != target_branch:
+                raise LookerError(f'checked out {target_branch!r} but Looker reports {now!r}')
+            sess.branch = now
+            out(f'Looker dev workspace now on {target_branch}; a Looker IDE tab shows it after a refresh')
+    else:
+        sess.set_mode('prod')
+        sess.branch = sess.current_branch()
+
+    for p in local:
+        os.remove(os.path.join(proj.root, *p.split('/')))
+    remote = sess.remote_files()
+    for p, data in remote.items():
+        proj.write_local(p, data)
+    cfg.update({'mode': target_mode, 'branch': target_branch})
+    proj.save_config()
+    proj.state = {'files': {}}
+    record(proj, sess, {p: sha(d) for p, d in remote.items()})
+    out(f'switched to {target_mode} ({where}); mirrored {len(remote)} file(s), removed {len(local)} old local file(s)')
+    return OK
+
+
+def version():
+    try:
+        from importlib.metadata import version as dist_version
+        return dist_version('looker-sync')
+    except Exception:
+        return 'unknown'
+
+
+def skill_file():
+    here = os.path.dirname(os.path.abspath(__file__))
+    for rel in (('_skills_data', 'looker-sync', 'SKILL.md'),            # installed wheel
+                ('..', '..', 'skills', 'looker-sync', 'SKILL.md')):      # source checkout
+        path = os.path.normpath(os.path.join(here, *rel))
+        if os.path.isfile(path):
+            return path
+    raise LookerError('SKILL.md is not packaged in this install')
+
+
+def cmd_skill(args):
+    try:
+        path = skill_file()
+    except LookerError as e:
+        out(f'LOOKER ERROR: {e}')
+        return LOOKER_ERROR
+    if args.path:
+        out(path)
+    else:
+        with open(path, encoding='utf-8') as f:
+            sys.stdout.write(f.read())
+    return OK
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(
+        prog='looker-sync', description=__doc__.split('\n\n')[0],
+        epilog='Run `looker-sync skill` for the full guide (workflows, guards, traps) written for agents.')
+    ap.add_argument('--version', action='version', version='looker-sync ' + version())
+    ap.add_argument('-C', '--project-dir', default='.', help='Looker project folder (default: cwd)')
+    ap.add_argument('--env-file', help='env file with LOOKER_URL, LOOKER_CLIENT_ID, LOOKER_CLIENT_SECRET')
+    sub = ap.add_subparsers(dest='cmd', required=True)
+    p = sub.add_parser('init', help='set up this folder (works when empty), then a first pull')
+    p.add_argument('--project', help='Looker project id; asked for on a terminal if omitted')
+    p.add_argument('--mode', choices=['dev', 'prod'], default='dev')
+    p.add_argument('--branch', help="default: the branch Looker's dev workspace is on")
+    p.add_argument('--include', nargs='+')
+    p.add_argument('--exclude', nargs='+')
+    p.add_argument('--no-pull', action='store_true', help='write the metadata only')
+    p.add_argument('--force', action='store_true', help="take Looker's copy over files already in the folder")
+    p = sub.add_parser('pull', help='copy Looker files to disk; never deletes local files')
+    p.add_argument('--force', action='store_true', help="take Looker's copy over unpushed local changes")
+    p.add_argument('--dry-run', action='store_true')
+    sub.add_parser('status', help='show what differs; writes nothing')
+    p = sub.add_parser('push', help='write local changes, read them back, validate')
+    p.add_argument('--force', action='store_true', help='overwrite files changed in Looker since the last sync')
+    p.add_argument('--delete', action='store_true', help='delete files that exist only in Looker')
+    p.add_argument('--dry-run', action='store_true')
+    p = sub.add_parser('switch', help='move Looker and the folder to another branch or mode')
+    g = p.add_mutually_exclusive_group(required=True)
+    g.add_argument('--branch')
+    g.add_argument('--mode', choices=['dev', 'prod'])
+    p.add_argument('--local-changes', choices=['push', 'backup', 'cancel'],
+                   help='what to do with unpushed local changes when there is no terminal')
+    p.add_argument('--yes', action='store_true', help='confirm the switch without a terminal')
+    p = sub.add_parser('skill', help='print the full usage guide written for agents')
+    p.add_argument('--path', action='store_true', help='print where the guide file is instead')
+    args = ap.parse_args(argv)
+    if args.cmd == 'skill':
+        return cmd_skill(args)
+    proj = Project(args.project_dir)
+    try:
+        return {'init': cmd_init, 'pull': cmd_pull, 'status': cmd_status,
+                'push': cmd_push, 'switch': cmd_switch}[args.cmd](proj, args)
+    except Refused as e:
+        out(f'REFUSED: {e}')
+        return REFUSED
+    except LookerError as e:
+        out(f'LOOKER ERROR: {e}')
+        return LOOKER_ERROR
+
+
+if __name__ == '__main__':
+    sys.exit(main())