> For the complete documentation index, see [llms.txt](https://docs.smartmerge.de/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.smartmerge.de/using-smart-merge-v/command-line-interface.md). # Command Line Interface Use the Smart Merge V CLI for terminal Quick Merge and Server Watcher automation. The Smart Merge V CLI is for server owners and experienced maintainers who want to run Smart Merge V from a terminal. It can run Quick Merge, check task status, show account information, and run Server Watcher without keeping the full desktop window open. {% hint style="warning" %} The CLI is an automation tool. If this is your first merge, start with the web or desktop Quick Merge flow so you can see the review screens before using terminal commands. {% endhint %} ## Download and start 1. Download [smartmerge-cli.zip](https://app.smartmerge.de/downloads/smartmerge-cli.zip). 2. Extract the ZIP on the machine that can access your server resources. 3. Open a terminal in the extracted folder. 4. Confirm the CLI starts: ```bash node smartmerge-cli.mjs help ``` The released CLI requires Node.js 24 or newer. {% hint style="info" %} You may see `pnpm cli ...` in developer notes for the Smart Merge V app repository. Customer releases use `node smartmerge-cli.mjs ...` from the downloaded archive. {% endhint %} ## Sign in Run: ```bash node smartmerge-cli.mjs login ``` The CLI prints a Smart Merge V web handoff URL and asks for the exchange code shown by the web app. If you already have the exchange code, you can pass it directly: ```bash node smartmerge-cli.mjs login --exchange ``` Check the stored login: ```bash node smartmerge-cli.mjs whoami ``` Remove stored credentials: ```bash node smartmerge-cli.mjs logout ``` ## Authentication options Most users should use `login`. Automation can also provide a token. | Method | Example | Notes | | ----------------- | --------------------------------------------------------- | --------------------------------------------------- | | Stored login | `node smartmerge-cli.mjs login` | Best for an interactive server terminal. | | Token flag | `node smartmerge-cli.mjs merge ./resources --token ` | Overrides environment and stored login for one run. | | Environment token | `SMARTMERGE_TOKEN=` | Useful for services or scheduled jobs. | Token priority is: 1. `--token ` 2. `SMARTMERGE_TOKEN` 3. stored CLI login Stored credentials are tied to the API URL they were created for. If you change `SMARTMERGE_API_URL`, sign in again so the CLI does not reuse credentials for the wrong API. ## Run Quick Merge Use `merge` with one or more folders or files: ```bash node smartmerge-cli.mjs merge ./resources ./more-resources ``` The CLI checks for Smart Merge V conflict groups, prints a summary, creates a merge task, follows progress, and prints the task page plus result download URL when the task finishes. Useful options: | Option | What it does | | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--yes` | Upload without the interactive confirmation prompt. | | `--target-dlc ` | Override the detected target FiveM build or DLC. Use the Smart Merge V value from [Supported Gamebuilds](/core-concepts/core-concepts/supported-gamebuilds.md), not the raw build number. The value you pass is used exactly as given; if it is not an accepted target, the CLI rejects it and lists the accepted options. | | `--gamebuild-dependency` | Include the gamebuild dependency in the generated output. | | `--no-gamebuild-dependency` | Do not include the gamebuild dependency. This is the default. | | `--no-resource-dependency` | Do not include dependent resource names. | | `--poll-interval ` | Change how often the CLI checks task progress. | | `--token ` | Use a token for this run instead of stored login. | Example: ```bash node smartmerge-cli.mjs merge ./resources --target-dlc mp2025_02 --yes ``` CLI Quick Merge requires an active Smart Merge V subscription. Free merge quota alone does not unlock CLI merging. See [Merge Allowances](/core-concepts/core-concepts/merge-allowances.md) for what each plan includes. ## Check task status and download links Check an existing task: ```bash node smartmerge-cli.mjs status ``` Finished task output includes: * task page URL * result download URL * result type * target platform and target DLC when available The download URL requires either an `Authorization: Bearer ` header or an active Smart Merge V browser session. If the result is not `Success`, the download can be unavailable or incomplete. ## Account overview Show account and Smart Merge V overview information: ```bash node smartmerge-cli.mjs overview ``` `history` is an alias for `overview`. ## CLI Server Watcher The CLI can run Server Watcher from a terminal. It saves your watcher setup, checks the selected resources folder, creates merge tasks when conflicts appear, and follows those tasks to completion. Finished results stay ready for your review and guided installation, so the CLI does not make uncertain changes to your server files. Set it up: ```bash node smartmerge-cli.mjs watch setup ./resources --daily-run 03:00 ``` If your `server.cfg` is not detected automatically, pass it explicitly: ```bash node smartmerge-cli.mjs watch setup ./resources --server-cfg ../server.cfg ``` Setup options: | Option | What it does | | -------------------------- | ---------------------------------------------------------------- | | `--daily-run ` | Local time for the daily precheck. Default is `03:00`. | | `--server-cfg ` | Use a specific `server.cfg` path instead of automatic detection. | | `--gamebuild-dependency` | Include the gamebuild dependency in watcher-created tasks. | | `--no-resource-dependency` | Do not include dependent resource names. | Run the watcher: ```bash node smartmerge-cli.mjs watch run ``` By default, `watch run` starts a parent supervisor that restarts the worker after recoverable crashes until you stop it with `Ctrl+C`. Run one check and exit: ```bash node smartmerge-cli.mjs watch run --once ``` `--once` runs one check, waits for any created task, reports the finished result, then exits. It returns a nonzero exit code if the created task finishes with a non-success result. Inspect saved watcher state: ```bash node smartmerge-cli.mjs watch status ``` Run options: | Option | What it does | | --------------------------- | ----------------------------------------------------------------------- | | `--once` | Run one check, wait for any created task, report the result, then exit. | | `--no-supervisor` | Run without the parent restart supervisor. | | `--poll-interval ` | Change the active task polling interval. | | `--token ` | Use a token for this run instead of stored login. | ## Guided installation When a watcher task finishes, the CLI leaves the watched folder unchanged and points you to the finished task. Follow the task's file and manifest steps, then install the downloaded generated group. | Result | CLI behavior | | ----------------------------------------- | ------------------------------------------------------------------- | | Merge is ready | Prints the task and result details for guided installation. | | A file or manifest needs attention | Leaves the watched folder unchanged and prints what to review next. | | The result cannot be prepared confidently | Makes no server changes and tells you what to review next. | Unrelated custom resource folders are preserved. ## server.cfg updates You can provide `server.cfg` during setup so Server Watcher can read the target build and understand the server context. Current guided results do not modify it automatically. After completing the task checklist, add the generated group after the resources it needs. ```cfg ensure map_pack_a ensure map_pack_b ensure [smartmerge_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee] set onesync on ``` Complete any task-listed file actions first, then add the generated group after the resources it needs. ## Environment variables | Variable | What it does | | -------------------------- | -------------------------------------------------------------- | | `SMARTMERGE_TOKEN` | Token fallback for authentication. | | `SMARTMERGE_API_URL` | Override the API base URL. Most users should leave this unset. | | `SMARTMERGE_APP_URL` | Override the web app URL used for login and task links. | | `SMARTMERGE_CONFIG_DIR` | Store CLI auth and watcher state in a custom directory. | | `SMARTMERGE_WATCH_POLLING` | Set to `true` to use polling-based folder watching. | ## Logs and exit codes The CLI prints prechecks, folder changes, conflicts, created tasks, result status, and guided next steps to stdout and stderr. For automation: * `merge` exits with a nonzero code when the finished task result is not `Success`. * `watch run --once` exits with a nonzero code when it created a task and that task finishes with a non-success result. * long-running `watch run` is intended to keep running until you stop it. Use [Processing Logs](/using-smart-merge-v/processing-logs.md) to understand task log severities. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.smartmerge.de/using-smart-merge-v/command-line-interface.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.