RuleSync CLI Docs

Welcome to the RuleSync CLI documentation.

What is RuleSync CLI?

RuleSync CLI is the command-line client for authenticating against RuleSync, syncing shared files into a local repository, comparing local files with remote output, publishing new file versions, and inspecting your current configuration.

The source of truth for this page is the current implementation in packages/cli/src. This page describes what the CLI actually does today, not an aspirational surface.

You can run the CLI directly with npx rulesync-cli. If you omit a subcommand, it defaults to pull.

How to use the docs

This page is organized into three parts:

Getting Started: what the CLI is, how the page is organized, and the shortest path to a working setup.
Commands: every current command, its usage shape, and the actual behavior implemented in source.
Reference: flags, sync semantics, and config file behavior.

Quick start

# 1. Authenticate once
npx rulesync-cli login

# 2. Pull all account files into the current repo
npx rulesync-cli pull

# 3. Optional: auto-sync on install
"scripts": { "postinstall": "npx rulesync-cli pull -y" }

The CLI stores auth in ~/.rulesync/auth.json. No per-project config file is needed; all files visible to your account are synced by default.

Default behavior

Runs pull by default when you do not pass a subcommand.

Usage

npx rulesync-cli

Equivalent to running `npx rulesync-cli pull`.
Uses your saved auth config in `~/.rulesync/auth.json`.
Syncs all files visible to your authenticated account by default.

login

Opens a browser, completes auth, and saves your CLI credentials locally.

Usage

npx rulesync-cli login [--dev] [--port <port>]

Starts a temporary local HTTP callback server on a random port.
Opens `/cli/auth?callback_port=...` in your browser and waits up to 5 minutes for authorization.
Saves the API key and API URL to `~/.rulesync/auth.json`.
Supports `--dev` and `--port` for local development against `http://localhost:<port>`.

init

Deprecated command kept for backward compatibility.

Usage

npx rulesync-cli init

This command is deprecated.
It no longer creates or uses `.rulesync.json`.
It no longer prompts for an output path or writes file configuration.
Use `pull` and the current CLI workflow instead.

pull

Fetches remote files, previews changes, writes them locally, and creates symlinks when configured.

Usage

npx rulesync-cli pull [-y|--yes] [--dev] [--port <port>]

Fetches sync output from `/api/sync` and can handle either a single generated file or multiple files returned by the server.
Shows the files and versions that are about to be applied before it writes anything.
Creates parent directories automatically before writing files.
Creates configured symlinks and leaves existing non-symlink files alone.
Ignores RuleSync timestamp-only changes so unchanged files do not get rewritten just because `Last synced` changed.
With `-y` / `--yes`, auto-writes normal files, but `ask` pull-type files still show a diff and require confirmation.

diff

Shows the difference between local files and the current remote output. Optionally filter to a single output path.

Usage

npx rulesync-cli diff [outputPath] [--dev] [--port <port>]

Uses the same sync payload as `pull`, but does not write files.
Pass an optional `[outputPath]` argument to show only the diff for that file.
Shows unified diffs with colored additions, removals, and context lines.
Reports new files when a local file does not exist yet.
Ignores timestamp-only changes when deciding whether a file differs.

list

Lists your remote files and checks whether each local output file exists.

Usage

npx rulesync-cli list [--dev] [--port <port>]

Loads remote files from `/api/rulesets` and shows output path, pull type, symlinks, and updated date.
Marks missing local files directly in the table.
Marks missing symlink targets inline so you can see which links still need a `pull`.
Lists all files visible to your authenticated account; no project config file is required.

push

Publishes a local file as a new version of an existing remote file.

Usage

npx rulesync-cli push <file> [--dev] [--port <port>]

Takes a required `<file>` argument — the path to the local file to upload.
Auto-determines the target file by matching the file path against remote files from `/api/sync`.
Falls back to prompting for a slug manually when no matching file is found.
Prints the published version number after the upload succeeds.

status

Prints the current auth status.

Usage

npx rulesync-cli status

Shows whether auth is configured and prints the configured API URL.
Shows the saved API key prefix for quick verification.
Does not require a project config file; all account files are available by default.

Flags

Flag	Commands	Behavior
`-v, --version`	Global	Prints the CLI version and exits.
`-y, --yes`	pull	Skips normal write approval prompts. `ask` pull-type files still require confirmation.
`--dev`	login, pull, diff, list, push	Uses localhost instead of `https://rulesync.dev`.
`--port <port>`	login, pull, diff, list, push	Overrides the localhost port when `--dev` is set. Defaults to `3000`.

Sync behavior

Config files

Auth config lives in `~/.rulesync/auth.json` and is created by `login`.
A `.rulesync.json` file may still exist in a repo from older setups, but the current CLI ignores it.
Syncing is account-wide by default and uses the files visible to the authenticated account.

Without .rulesync.json

`pull` works with no project setup and syncs all files visible to your account.
`diff` compares against the same full-account sync output.
`status` can still report that no `.rulesync.json` project file exists, but that does not block syncing.
`push` also works without `.rulesync.json` and applies account-wide by default.

Pull modes

`replace` writes the remote file content directly.
`ask` shows a diff and asks before writing, even when you passed `--yes`.
Timestamp lines are ignored when comparing old and new content, so a file is not rewritten just because the sync timestamp changed.

Repo context

When the current directory is a Git repo, the CLI sends the repo root folder name as the `X-RuleSync-Project` header.
Most file paths resolve relative to the current working directory.
Remote output paths and symlink paths can expand `~` to your home directory when the CLI writes or inspects them.

Account-wide sync defaults

The CLI no longer uses a per-project .rulesync.json file. If one exists from a previous setup, it is ignored. All commands operate on the full set of files visible to the authenticated account.

Run `npx rulesync-cli login` once to store credentials in `~/.rulesync/auth.json`.
All subsequent commands (`pull`, `diff`, `list`, `push`, `status`) use those credentials automatically.
No project config file is created, expected, or required.