> ## Documentation Index > Fetch the complete documentation index at: https://docs.locality.dev/llms.txt > Use this file to discover all available pages before exploring further. # CLI reference > Developer-friendly reference for loc commands, arguments, workflows, JSON output, sync review, daemon control, and virtual filesystem providers. `loc` is the supported command surface for Locality. Use it to connect sources, register mounts, inspect local sync state, review remote write plans, push approved edits, and operate the background daemon and virtual filesystem providers. Most developer and agent workflows should stay path-scoped: ```bash theme={null} loc status loc diff loc push -y ``` Use `--json` on commands when integrating with scripts, agents, tests, or MCP tools. Help output is always text, even when `--json` is present. ```bash theme={null} loc --help loc mount notion --help loc push --json -y ``` ## Command map | Task | Commands | Use when | | ------------------------ | --------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | | Connect accounts | `connect`, `connections`, `profiles`, `connection show`, `disconnect` | You need to authenticate Notion or Google Docs and inspect saved connection metadata. | | Register local files | `mount notion`, `mount google-docs`, `file-provider register`, `pull` | You want a remote workspace to appear as local Markdown. | | Navigate mounted content | `search`, `info`, `status`, `inspect` | You need to find content or understand what Locality knows about a path. | | Review sync state | `status`, `diff`, `pull`, `push`, `restore`, `log`, `undo` | You are deciding whether to update local files or write local edits back to the source. | | Run background services | `daemon`, `file-provider`, `doctor` | You are using Live Mode, macOS File Provider, Linux FUSE, or Windows Cloud Files. | | Create local content | `create page`, `templates`, `okf export` | You want safe local drafts, local workflow packs, or a portable export. | | Integrate tools | `mcp`, `--json` | You are building agent or automation surfaces over Locality. | ## Conventions ### Paths and scope Commands that accept a path resolve it through the registered Locality mount table. Prefer the narrowest useful path: a single `page.md`, one page directory, or a small subtree. Broad workspace-level `diff` and `push` commands are harder to review. When a path is optional, Locality uses the current working directory when it is inside a mount. Outside a mount, commands such as `loc status` report registered mounts in the active state directory. ### `--json` `--json` is global: ```bash theme={null} loc --json status loc status --json ``` JSON output is intended for tools. It does not include OAuth tokens, refresh tokens, personal access tokens, client secrets, or credential-store references. ### State directory Production state defaults to `~/.loc`. For isolated development and tests, use `LOCALITY_STATE_DIR` or daemon flags such as `--state-dir `. ### Projection modes Projection support depends on the host platform: | Platform | Supported values | | -------- | ------------------------------------ | | macOS | `plain-files`, `macos-file-provider` | | Linux | `plain-files`, `linux-fuse` | | Windows | `plain-files`, `windows-cloud-files` | `plain-files` writes normal files during `loc pull`. The virtual projection modes list online-only content through the platform provider and materialize file bodies on open or explicit pull. ## Connect sources ### `loc connect notion` Connect a Notion workspace and save a reusable connection. ```bash theme={null} loc connect notion [--name ] [--token-stdin] [--no-browser] [--direct-oauth] [--broker-url ] [--redirect-uri ] ``` Use this before mounting Notion. The default path uses Locality's OAuth broker, opens a browser, and stores credentials in the local credential store. Locality can mount only pages and workspaces shared with the Notion integration. Key arguments: | Argument | Meaning | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `--name ` | Connection id to save. Runtime default is `notion-default` when no active Notion connection exists; pass an explicit name for reproducible setup. | | `--token-stdin` | Read a Notion integration token from stdin. Useful for local development and CI. | | `--no-browser` | Print the OAuth URL instead of opening it. Useful for remote shells. | | `--direct-oauth` | Use direct OAuth credentials from the environment instead of the broker. Developer path only. | | `--broker-url ` | Override the OAuth broker base URL. | | `--redirect-uri ` | Override the local callback URI. | Examples: ```bash theme={null} loc connect notion --name notion-default loc connect notion --name work --no-browser echo "$NOTION_TOKEN" | loc connect notion --token-stdin --name notion-ci ``` ### `loc connect google-docs` Connect Google Docs through the Locality OAuth broker. ```bash theme={null} loc connect google-docs [--name ] [--no-browser] [--broker-url ] [--redirect-uri ] ``` Use this before mounting a Google Drive workspace folder that contains Google Docs. Non-Google-Docs Drive files are ignored by the Google Docs connector. Key arguments: | Argument | Meaning | | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--name ` | Connection id to save. Runtime default is `google-docs-default` when no active Google Docs connection exists; pass an explicit name for reproducible setup. | | `--no-browser` | Print the OAuth URL instead of opening it. | | `--broker-url ` | Override the OAuth broker base URL. | | `--redirect-uri ` | Override the local callback URI. | Example: ```bash theme={null} loc connect google-docs --name google-docs-default ``` ### Inspect and remove connections ```bash theme={null} loc connections loc profiles loc connection show loc disconnect ``` Use `connections` to list saved account connections. Use `profiles` to list connector auth profiles and capabilities. Use `connection show` for one connection's metadata. These commands never print secrets. `disconnect` deletes the credential and marks the connection revoked. It does not remove mounts; affected mounts will report auth or revoked-connection problems until you reconnect or remount. ## Mount sources ### `loc mount notion` Register Notion content at a local path. ```bash theme={null} loc mount notion (--workspace|--root-page ) [--connection ] [--mount-id ] [--projection ] [--read-only] ``` Use `--workspace` for all Notion content shared with the integration. Use `--root-page ` when you want one page tree instead of the whole accessible workspace. Key arguments: | Argument | Meaning | | ----------------------- | ---------------------------------------------------------------------------------------------------- | | `` | Local directory to register as the mount. | | `--workspace` | Mount all accessible Notion workspace content shared with the integration. | | `--root-page ` | Mount one Notion page tree. Mutually exclusive with `--workspace`. | | `--connection ` | Use a specific saved connection. Required when Locality cannot choose safely. | | `--mount-id ` | Stable id for scripts, provider commands, logs, and status output. | | `--projection ` | `plain-files`, `macos-file-provider`, `linux-fuse`, or `windows-cloud-files`, depending on platform. | | `--read-only` | Register the mount as read-only and block push operations. | Examples: ```bash theme={null} loc mount notion ~/Library/CloudStorage/Locality/notion-main --workspace --projection macos-file-provider loc mount notion ~/Locality/notion-page --root-page --projection plain-files loc mount notion ~/Locality/company --workspace --connection notion-company --mount-id notion-company ``` After a virtual mount, register or open the platform provider: ```bash theme={null} loc file-provider register notion-main loc file-provider open notion-main ``` For a plain-file mount, pull once to write the local projection: ```bash theme={null} loc pull ~/Locality/notion-page ``` ### `loc mount google-docs` Register Google Docs content under a Drive workspace folder. ```bash theme={null} loc mount google-docs --workspace-folder [--connection ] [--mount-id ] [--projection ] [--read-only] ``` Use this when a Google Drive folder is the workspace boundary for Locality. The folder can be specified by name, id, or folder URL. Key arguments: | Argument | Meaning | | --------------------------------- | -------------------------------------------------------------- | | `` | Local directory to register as the mount. | | `--workspace-folder ` | Google Drive folder name, folder id, or folder URL. | | `--connection ` | Saved Google Docs connection to use. | | `--mount-id ` | Stable mount id. Defaults to a Google Docs mount id when safe. | | `--projection ` | Platform-specific projection mode. | | `--read-only` | Block push operations for this mount. | Examples: ```bash theme={null} loc mount google-docs ~/Locality/google-docs-main --workspace-folder "Locality" --projection plain-files loc mount google-docs ~/Locality/google-docs-main --workspace-folder --connection google-docs-default loc pull ~/Locality/google-docs-main ``` ## Find and inspect content ### `loc search` Search local mount metadata without contacting remote sources. ```bash theme={null} loc search [--connector ] [--limit ] [--all] ``` Use search for navigation, desktop typeahead, agent path lookup, and source URL resolution. It reads local SQLite metadata only, so it is fast and safe but may not know about the newest remote changes until a pull, daemon refresh, or freshness check has run. Key arguments: | Argument | Meaning | | ------------------------- | -------------------------------------------------------------------------------- | | `` | Title, path fragment, remote id, or source URL. Multi-word queries are accepted. | | `--connector ` | Limit results to one connector, such as `notion` or `google-docs`. | | `--limit ` | Maximum number of results. Defaults to `10`. | | `--all` | Include stale, disconnected, or inactive mount access. | Examples: ```bash theme={null} loc search roadmap loc search "Launch Plan" --connector notion loc search "https://www.notion.so/..." --connector notion --json ``` ### `loc info` Show source, mount, entity, child, and journal context for a path using local state only. ```bash theme={null} loc info [path] ``` Use `info` when you need to answer "what is this file connected to?" without hydrating content or calling the remote connector. It is useful before deleting or moving suspicious files in a mount. Examples: ```bash theme={null} loc info . loc info ~/Locality/notion-main/engineering/page.md --json ``` ### `loc status` Show local sync state for one path, the current mount scope, or all mounts. ```bash theme={null} loc status [path] ``` Use status before and after edits. It reports stubs, dirty files, conflicts, missing projections, pending journals, failed journals, remote-update metadata already observed by the daemon, and read-only state. It does not call remote connectors itself. Examples: ```bash theme={null} loc status loc status loc status ~/Locality/notion-main --json ``` Common states: | State | Meaning | Usual next command | | ------------------------- | -------------------------------------------------------- | ------------------------------- | | `all_synced` | Local, remote, and synced shadow are aligned. | Keep working. | | `stub` | Locality knows the object, but the body is not hydrated. | `loc pull ` | | `pending_local_changes` | Local file changed and needs review. | `loc diff ` | | `remote_update_available` | Remote moved while the local file is clean. | `loc pull ` | | `review_needed` | Local and remote state both need attention. | `loc inspect ` | | `conflicted` | Conflict markers or conflicted state exist. | Resolve, then `loc diff ` | ### `loc inspect` Explain local and remote sync state for one path. ```bash theme={null} loc inspect ``` Use inspect when status says remote state may have changed and you need a more authoritative explanation before choosing pull, push, or manual merge. Unlike `status`, `inspect` may call the remote connector. It is read-only: it does not rewrite local files, update shadows, or mutate the remote source. Example: ```bash theme={null} loc inspect ~/Locality/notion-main/roadmap/page.md --json ``` ### `loc doctor` Run read-only diagnostics for daemon, state store, mounts, providers, projection support, and auth. ```bash theme={null} loc doctor ``` Use doctor when a mount is not appearing, a daemon/provider seems stopped, auth is failing, or you want a broad health report. It reports suggested recovery commands but does not initialize state, write credentials, start daemons, register providers, or reset anything. Example: ```bash theme={null} loc doctor --json ``` ## Review and sync ### `loc pull` Pull remote content into the local projection. ```bash theme={null} loc pull ``` Use pull to hydrate stubs, refresh a page or subtree, update clean files after remote changes, or write a plain-file mount after registration. Pull refuses to overwrite dirty hydrated content. On virtual filesystem mounts, it updates daemon/cache state and materialized visible files only when they are still clean relative to the synced shadow. Examples: ```bash theme={null} loc pull ~/Locality/notion-main loc pull ~/Locality/notion-main/engineering/roadmap/page.md loc pull --json ``` ### `loc diff` Preview the remote write plan for local changes. ```bash theme={null} loc diff ``` Use diff before every explicit push. It parses the mounted Markdown, compares it with the synced shadow, validates Locality metadata, detects unresolved conflict markers, and shows the connector-neutral operations that `push` would attempt. It does not mutate local files or remote content. Examples: ```bash theme={null} loc diff loc diff ~/Locality/notion-main/engineering --json ``` ### `loc push` Push local changes back to the remote source. ```bash theme={null} loc push [-y|--yes] [--confirm] ``` Use push only after reviewing `loc diff` or when Live Mode has paused and asks for a manual decision. The push pipeline runs the same validation and planning as `diff`, then uses a journaled connector apply path. Key arguments: | Argument | Meaning | | ------------- | ----------------------------------------------------------------------------------------- | | `` | File or directory scope to push. Prefer a narrow path. | | `-y`, `--yes` | Approve safe non-empty plans without prompting. Use for reviewed automation. | | `--confirm` | Approve plans that trip destructive-change guardrails. Use only after reviewing the plan. | Examples: ```bash theme={null} loc push -y loc push --confirm loc push --json -y ``` If the remote changed first, pull before pushing: ```bash theme={null} loc pull loc diff loc push -y ``` If the file contains conflict markers, edit it to the intended final content, remove every marker line, then run `loc diff` again. ### `loc restore` Restore a local file from the last synced shadow. ```bash theme={null} loc restore [--force] ``` Use restore when local edits should be discarded. It rewrites the local file from Locality's last synced snapshot and does not call Notion or Google Docs. Failed push journals remain in the audit log. `--force` allows restoring a file marked conflicted. Use it only when you have chosen to discard local conflict content. Examples: ```bash theme={null} loc restore loc restore --force ``` ### `loc log` List push journal entries. ```bash theme={null} loc log [path] ``` Use log to inspect previous push attempts, failed journals, and journal ids for undo. With a path, Locality filters to entries that touched that entity or scope. Examples: ```bash theme={null} loc log loc log --json ``` ### `loc undo` Undo a reconciled push using its journal id. ```bash theme={null} loc undo ``` Use undo for journal-backed recovery where the connector supports the reverse operations. It is not a generic remote history browser. Failed or partially applying journals may be unsafe to undo automatically. Example: ```bash theme={null} loc log loc undo ``` ## Create local drafts and exports ### `loc create page` Create a local page draft in a mounted Locality folder. ```bash theme={null} loc create page --title [--parent <dir>] [--private] ``` Use this to create the filesystem shape for a new page without calling the remote connector. The containing directory determines the remote parent when the draft is pushed. When `--parent` is omitted, Locality uses the current directory. Key arguments: | Argument | Meaning | | ----------------- | ---------------------------------------------------------------------------------- | | `--title <title>` | Title for the new page and the generated folder/file name. Required. | | `--parent <dir>` | Existing mounted directory where the page should be created. | | `--private` | For Notion, create as a workspace-private page on push when the token supports it. | Example: ```bash theme={null} loc create page --title "Launch Plan" --parent ~/Locality/notion-main/go-to-market loc diff ~/Locality/notion-main/go-to-market/Launch\ Plan/page.md loc push ~/Locality/notion-main/go-to-market/Launch\ Plan/page.md -y ``` ### `loc templates` Manage local-first template packs. ```bash theme={null} loc templates list loc templates validate <path> loc templates new <pack> <path> [--force] loc templates apply <pack> <template> --to <dir> [--title <title>] [--force] ``` Use templates for repeatable local workflows, such as progress logs or draft documents. Template commands write local files only. They do not connect sources, mount workspaces, bypass diff review, or push remote changes. Key forms: | Command | Use when | | -------------------------------------------------- | -------------------------------------------------------------------- | | `loc templates list` | You want bundled pack ids. | | `loc templates validate <path>` | You are developing or reviewing a pack. | | `loc templates new <pack> <path>` | You want a complete local workspace from a pack. | | `loc templates apply <pack> <template> --to <dir>` | You want one generated draft in an existing local or mounted folder. | Examples: ```bash theme={null} loc templates list loc templates validate ./templates/packs/founder-proof-of-work loc templates new founder-proof-of-work ~/Locality/founder-proof loc templates apply founder-proof-of-work weekly-update --to ~/Locality/notion-main --title "Week 28 Update" ``` ### `loc okf export` Export mounted content as an Open Knowledge Format bundle. ```bash theme={null} loc okf export <path> --out <dir> ``` Use OKF export when an agent, search pipeline, or review process needs a portable Markdown bundle instead of live mounted files. The command reads the source projection and writes a separate output directory. It is read-only with respect to Locality state and the remote source. `--out <dir>` must point to an empty output directory. Example: ```bash theme={null} loc okf export ~/Locality/notion-main/engineering-wiki --out ~/Desktop/engineering-wiki-okf ``` ## Daemon and virtual filesystem providers ### `loc daemon` Start, stop, reload, restart, or inspect the background `localityd` process. ```bash theme={null} loc daemon start [--session] [--launchd] [--localityd-bin <path>] [--state-dir <path>] [--tcp-addr <address-or-off>] [--include-env <KEY>] loc daemon stop [--state-dir <path>] [--tcp-addr <address-or-off>] loc daemon status [--state-dir <path>] [--tcp-addr <address-or-off>] loc daemon reload [--state-dir <path>] [--tcp-addr <address-or-off>] loc daemon restart [--session] [--launchd] [--localityd-bin <path>] [--state-dir <path>] [--tcp-addr <address-or-off>] [--include-env <KEY>] ``` Use the daemon for Live Mode, virtual filesystems, background hydration, freshness checks, and managed provider workflows. Subcommands: | Command | Use when | | --------- | --------------------------------------------------------------------------- | | `start` | Start `localityd` under the platform process manager or a detached session. | | `stop` | Stop the managed daemon. | | `status` | Check manager state, IPC reachability, watched mounts, and queue counts. | | `reload` | Ask a running daemon to reconcile watches with the current mount table. | | `restart` | Stop then start the daemon after config or binary changes. | Key arguments: | Argument | Meaning | | ----------------------------- | --------------------------------------------------------------------------------------------------------------------- | | `--session` | Run as a detached session process. Useful for development and non-macOS hosts. | | `--launchd` | Use launchd. macOS only. | | `--localityd-bin <path>` | Launch a specific daemon binary. | | `--state-dir <path>` | Use an isolated Locality state directory. | | `--tcp-addr <address-or-off>` | Configure daemon TCP IPC, for example `127.0.0.1:8758`, or pass `off` where TCP can be disabled. Required on Windows. | | `--include-env <KEY>` | Pass one environment variable into the managed daemon. Repeatable. | Examples: ```bash theme={null} loc daemon start loc daemon status --json loc daemon reload loc daemon restart --session --localityd-bin ./target/debug/localityd ``` ### `loc file-provider` Manage the platform virtual filesystem provider for a mount. ```bash theme={null} loc file-provider register <mount-id-or-path> loc file-provider start <mount-id-or-path> loc file-provider run <mount-id-or-path> loc file-provider stop <mount-id-or-path> loc file-provider status <mount-id-or-path> loc file-provider restart <mount-id-or-path> loc file-provider open <mount-id-or-path> loc file-provider unregister <mount-id-or-path> loc file-provider list loc file-provider reset ``` Use this command with `macos-file-provider`, `linux-fuse`, and `windows-cloud-files` projection modes. The target can be a mount id such as `notion-main` or a path inside a mount. Subcommands: | Command | Use when | | ------------ | -------------------------------------------------------------------------------------------- | | `register` | Register, repair, or re-register the platform provider for a mount. | | `start` | Start the background provider runtime when the platform needs one. | | `run` | Run the Windows Cloud Files provider in the foreground for debugging. | | `stop` | Stop the provider runtime without necessarily unregistering the mount. | | `status` | Inspect provider registration, runtime state, daemon reachability, and logs. | | `restart` | Stop and start the provider runtime. | | `open` | Open the user-visible mount folder. | | `unregister` | Remove provider registration for the mount. On Linux, this removes the systemd user service. | | `list` | List provider domains or registrations known to the platform helper. | | `reset` | Reset provider registration state for recovery or development. | Examples: ```bash theme={null} loc file-provider register notion-main loc file-provider status notion-main --json loc file-provider restart ~/Locality/notion-main loc file-provider open notion-main ``` Platform notes: | Platform | Provider behavior | | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | macOS | Uses the signed Locality File Provider helper from the app bundle. `LOCALITY_FILE_PROVIDERCTL` can override the helper during development. | | Linux | Uses `locality-fuse` and a user `systemd` service for the shared FUSE root. `LOCALITY_FUSE_BIN` can override the helper during development. | | Windows | Uses Cloud Files sync-root registration and a `locality-cloud-files.exe` provider runtime. `LOCALITY_CLOUD_FILES_BIN` can override the helper during development. | ## Tool integration and development ### `loc mcp` Run the Locality MCP stdio server. ```bash theme={null} loc mcp ``` Use this from an MCP client configuration. It speaks over stdin/stdout and is not meant to be run as an interactive shell command. ### `loc config` Reserved for future configuration commands. ```bash theme={null} loc config ``` The current CLI exposes the command, but it prints `not implemented yet`. ### Development entrypoints From a source checkout: ```bash theme={null} make setup make dev-tauri make check make test make run-cli ARGS='status --json' ``` For isolated command tests: ```bash theme={null} LOCALITY_STATE_DIR="$(mktemp -d)" ./target/debug/loc status --json ``` ## Exit codes | Code | Meaning | | ---- | --------------------------------------------------------------------------------- | | `0` | Success, including some no-op commands. | | `1` | Internal, I/O, store, connector, auth, credential, daemon, or rate-limit failure. | | `2` | Usage error. | | `3` | Validation or diagnostic error. | | `4` | Confirmation, guardrail, or read-only policy required. | | `5` | Unsupported or intentionally unimplemented connector boundary. | ## Common workflows ### Connect, mount, pull, edit, push ```bash theme={null} loc connect notion --name notion-default loc mount notion ~/Locality/notion-main --workspace --projection plain-files --connection notion-default loc pull ~/Locality/notion-main $EDITOR ~/Locality/notion-main/engineering/roadmap/page.md loc status ~/Locality/notion-main/engineering/roadmap/page.md loc diff ~/Locality/notion-main/engineering/roadmap/page.md loc push ~/Locality/notion-main/engineering/roadmap/page.md -y ``` ### Use a virtual projection ```bash theme={null} loc daemon start loc mount notion ~/Locality/notion-main --workspace --projection linux-fuse loc file-provider register notion-main loc file-provider open notion-main loc file-provider status notion-main ``` Use `macos-file-provider` on macOS and `windows-cloud-files` on Windows. ### Recover from unwanted local edits ```bash theme={null} loc status <page.md> loc diff <page.md> loc restore <page.md> loc status <page.md> ``` ### Diagnose a paused or unhealthy mount ```bash theme={null} loc doctor loc daemon status loc file-provider status <mount-id-or-path> loc status <path> loc info <path> ```