Command line reference

CLI Docs

Doctrine ships a command line client as `dx`. Commands work against a local synced checkout, remote cloud files, or the underlying Doctrine API.

Quick Start

Installation and Setup

Install the CLI globally and log in once. The login flow opens a browser and stores the returned token in your local CLI config.

npm install -g @mp-lb/doctrine-cli
dx auth login

Three Ways to Use `dx`

Most CLI work starts with a local checkout: clone a store, edit files locally, then pull, push, or sync. For quick cloud-only inspection, use Linux-like commands such as `ls`, `cat`, `grep`, `find`, and `tree`. For scripts and setup flows, use the core API commands such as `store list`, `file read`, and `file write`.

See Local Checkout, Linux-Like Cloud Files, and Core API Commands for the full command lists.

dx clone workspace/project
cd project
dx pull
dx push --dry-run
dx sync

dx ls --store workspace/project
dx cat README.md --store workspace/project
dx grep -n "backend" docs --store workspace/project
dx find "*.md" --store workspace/project
dx tree src --store workspace/project

dx store list
dx file read README.md --store workspace/project

Local Checkout

This is the main CLI workflow. `dx clone` creates a local checkout of a cloud store, then `dx pull`, `dx push`, and `dx sync` move files explicitly between your local filesystem and Doctrine.

Clone a store

dx clone <workspace/store> [localPath] [--readonly]

Creates a local checkout, writes doctrine.yaml with sync config, and pulls files once.

Initialize a checkout

dx init <workspace/store>

Writes doctrine.yaml in the current directory using the resolved workspace/store config.

Convert a Git repo

dx git convert <workspace/store>

Creates or reuses a store, imports local files, and prepares the directory for Doctrine sync.

Inspect status

dx status dx s

Shows local changes that would be pushed, remote changes that would be pulled, and blocked paths.

Pull files

dx pull dx pull --direct --store <workspace/store>

Reads remote files into the local checkout. Direct pull skips checkout metadata and sync planning.

Push files

dx push [--force] [--dry-run|-d]

Uploads changed local text files and archives tracked files deleted locally. Dry run previews changes.

Sync files

dx sync [--watch] [--readonly]

Runs pull then push once, or stays in the foreground with watch mode. Readonly mode is pull-only.

Linux-Like Cloud Files

Use these commands when you want to inspect or edit cloud files without creating a local checkout. They are not POSIX commands, but they are designed to behave like the familiar shell commands where that maps cleanly to remote files.

List files

dx ls [directoryPath] --store <workspace/store>

Lists cloud files and directories with shell-like output. Directory results are printed with a trailing slash.

Read and concatenate files

dx cat README.md --store <workspace/store> dx cat README.md package.json --store <workspace/store>

Concatenates exact remote text files and prints their content. Binary files are rejected.

Search indexed content

dx search "text" --store <workspace/store> dx search-content "text" --store <workspace/store>

Uses the same indexed search backend as the web app. If content search is not enabled, use dx grep for dumb text search.

Grep text

dx grep "pattern" --store <workspace/store> dx grep -n -i "pattern" docs --store <workspace/store> dx grep -l "pattern" --store <workspace/store>

Recursively scans remote text files without using the search index. Supports common grep flags first.

Find paths

dx find --store <workspace/store> dx find "*.md" --store <workspace/store> dx find -name README.md --store <workspace/store>

Recursively walks remote directories and filters paths without requiring indexed search.

Print a tree

dx tree --store <workspace/store> dx tree promotion --store <workspace/store>

Recursively prints the selected store or a matching directory subtree as a box-drawing tree without requiring indexed search.

Diff text files

dx diff README.md README.old.md --store <workspace/store> dx diff README.md ./README.md --local --store <workspace/store>

Compares exact text files and prints a unified diff. Use --local to compare a remote file to a local file.

Manage paths

dx mkdir docs --store <workspace/store> dx mv old.md docs/new.md --store <workspace/store> dx cp README.md archive/README.md --store <workspace/store>

Creates directories, moves paths, and copies remote text files. Use dx cp -r for text directory trees.

Inspect text files

dx stat README.md --store <workspace/store> dx head -n 20 README.md --store <workspace/store> dx tail README.md --store <workspace/store> dx wc README.md --store <workspace/store>

Prints actual Doctrine metadata or common line, word, and byte views for remote text files.

Delete files

dx rm old.md --store <workspace/store> dx delete old.md --store <workspace/store>

Deletes one exact remote file path. These commands do not query-match or expand wildcards.

Core API Commands

These commands expose Doctrine API operations directly. They are useful for scripts, diagnostics, and setup, but creating stores is usually more natural in the web app.

Create a store

dx store create <workspace/store>

Creates a remote store in the selected workspace. Most users create stores in the web app, but the CLI exposes the API for scripts and setup flows.

List stores

dx store list dx store ls

Lists active remote stores available to the current CLI identity.

List files

dx file ls [directoryPath]

Calls the direct file-list API for a remote path. Use dx ls for the shorter Linux-like alias.

Read a file

dx file read <filePath> dx read <filePath>

Calls the direct file-read API for one remote text file. Use dx cat when you want shell-shaped concatenation.

Delete a file

dx file delete <filePath> --store <workspace/store>

Calls the direct file-delete API for one exact remote path. Use dx rm or dx delete for the Linux-like aliases.

Write a file

dx file write <filePath> <text> --store <workspace/store> dx write <filename-or-path> --file <localPath>

Writes UTF-8 text either to an exact remote path or to one unambiguous query match.

Query files

dx query <filename-or-path> [--store <workspace/store>] dx q <filename-or-path> -s <storeA>,<storeB>

Searches active, non-archived stores. One exact text match prints content; multiple matches print paths.

Duplicate a store

dx store duplicate <sourceStore> <newStore>

Copies text files from one store into a new store. Binary duplication is intentionally conservative.

Configuration

The CLI stores config in `~/.doctrine/config.json` unless `--state-dir` is supplied. Most users only need `dx auth login`, which stores the token automatically. Project-level config lives in `doctrine.yaml` or `doctrine.yml`.

  • `DOCTRINE_TOKEN` sets the auth token.
  • `token` and `poll-interval-ms` are supported config keys.
  • `defaults.store` can provide a default qualified `workspace/store` for direct store commands.

Auth, Config, and Client

Log in

dx auth login [--no-open]

Starts browser-based CLI authorization and stores the returned token in local CLI config.

Log out

dx auth logout

Clears the stored CLI token.

Check auth status

dx auth status

Prints whether a token is available from flags, environment, or stored config.

Show config

dx config show

Prints token state, poll interval, force-writes state, and the CLI state directory.

Set config

dx config set token <jwt> dx config set poll-interval-ms <milliseconds>

Writes a supported config value into the CLI state directory, which defaults to ~/.doctrine.

Open the terminal client

dx client dx tui

Starts the interactive terminal UI using your current login.

Options

--token <jwt>

dx --token <jwt> ...

Overrides the auth token for a command. The same value can be provided with DOCTRINE_TOKEN.

--store, -s

dx query README.md --store workspace/docs dx q README.md -s docs,notes

Limits query and query-write commands to one or more active stores.

--file <localPath>

dx write README.md --file ./README.md

Reads UTF-8 content from a local file for write commands instead of passing inline text.

--state-dir <path>

dx config show --state-dir ./tmp/cli-state

Uses an alternate CLI state directory instead of ~/.doctrine.

--force

dx file write /docs/readme.md '# Updated' --force

Allows supported write commands to replace existing remote content without version checks.

--readonly

dx sync --watch --readonly

Runs sync in pull-only mode and fails if tracked local files are modified or deleted.

Troubleshooting

  • If `dx store list` says authentication is required, run `dx auth login`.
  • If a globally linked command is stale after code changes, rebuild with `pnpm --filter @mp-lb/doctrine-cli build`.