CLI Docs

Doctrine ships a command line client as `doctrine` and `dx`. The short `dx` form is used throughout these docs. Commands work against the remote Doctrine workspace, a local synced mirror, or the terminal client.

Quick Start

Installation and Setup

Install the CLI globally, then log in. 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

Basic Commands

These cover the common cloud storage loop: list stores, create a store, inspect files, write content, and query by filename.

dx store list
dx store create my-notes
dx file ls /
dx write README.md "# Hello" -s my-notes
dx query README.md -s my-notes

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. The remaining config values are useful for scripts and local sync tuning.

  • `DOCTRINE_TOKEN` sets the auth token.
  • `token` and `poll-interval-ms` are supported config keys.

Cloud Storage

Use these commands to work with remote Doctrine stores and files: create stores, list directories, read or write text files, search across stores, and create read-only aliases.

Create a store

dx store create <storeId>

Creates a new remote store by writing an initial README.md at the store root.

List stores

dx store list dx store ls

Lists active remote stores by reading the workspace root and printing store ids.

Duplicate a store

dx store duplicate <sourceStoreId> <newStoreId>

Copies text files from one store into a new store. Binary files are not duplicated by the CLI yet.

List files

dx file ls [directoryPath] dx ls [directoryPath]

Lists files and directories under a remote path. Directory results are printed with a trailing slash.

Read a file

dx file read <filePath> dx read <filePath>

Reads a remote text file and prints its content. Binary files are rejected for text reads.

Inspect a file

dx file info <filePath>

Prints file metadata as JSON, including id, path, content type, version, file type, and alias details when relevant.

Create an alias

dx file alias <aliasPath> <targetPath>

Creates a read-only alias path that points at an existing target file.

Write a file by path

dx file write <filePath> <text> [--force] dx file write <filePath> --file <localPath> [--force]

Writes UTF-8 text to an exact remote path. Use --file to read content from disk instead of passing inline text.

Query files

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

Searches active, non-archived stores. If exactly one text file matches, the CLI prints its content. If multiple files match, it prints matching paths.

Write by query

dx write <filename-or-path> <text> [-s <storeIds>] [--force] dx write <filename-or-path> --file <localPath> [-s <storeIds>] [--force]

Uses the same server-side resolution as query. The write only happens when exactly one active file matches.

Local Sync

`dx clone` creates a local mirror of a store. The daemon reconciles local file changes with the remote workspace on a polling interval.

Clone a store

dx clone <storeId> [localPath] [--state-dir <path>] [--force]

Creates an empty local mirror, registers it as a sync instance, performs the first sync, and starts the daemon.

List sync instances

dx instances [--state-dir <path>]

Prints registered local mirrors with instance id, store id, local path, last sync time, and status.

Remove a sync instance

dx remove <instanceId> [--state-dir <path>]

Unregisters a local sync instance and removes its manifest from the CLI state directory.

Start the daemon

dx daemon start [--state-dir <path>] [--force]

Starts the background sync daemon. Current API, token, poll interval, and force settings are saved before launch.

Stop the daemon

dx daemon stop [--state-dir <path>]

Stops the background sync daemon when it is running.

Check daemon status

dx daemon status [--state-dir <path>]

Reports whether the daemon is running. When a heartbeat exists, it also prints update time, active instance count, and cycle duration.

Run daemon in foreground

dx daemon run [--state-dir <path>] [--force]

Runs the daemon in the current terminal process. This is useful for debugging sync behavior.

Auth, Config, and Client

Log in

dx auth login [--no-open]

Starts browser-based CLI authorization and stores the returned token in CLI config. Use --no-open if you want to open the verification URL yourself.

Log out

dx auth logout

Clears the stored CLI token.

Check auth status

dx auth status

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

Show config

dx config show [--state-dir <path>]

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

Get config

dx config get <token|poll-interval-ms>

Prints one stored config value.

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.

Unset config

dx config unset token dx config unset poll-interval-ms

Clears the token. Unsetting poll-interval-ms resets it to the default interval.

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 or stored as token.

--store, -s

dx query README.md --store 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. Do not pass inline text at the same time.

--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 write commands and daemon startup to use force-writes behavior when supported by the current command path.

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`.