Use Markyard from the command line

Before you begin

You need:

• Node.js 22 or newer with npm;
• your organization's Markyard URL, such as https://markyard.example.com; and
• a Markyard account with access to the documents you want to work with.

The npm package supports Apple Silicon macOS, x64 Linux, and x64 Windows. Install the public @markyardio/cli package globally; npm selects the native executable for your computer:

npm install --global @markyardio/cli

Install the user-facing package rather than one of the operating-system-specific implementation packages. Then check the installation:

markyard --version
markyard --help

Keep the CLI updated

When the CLI starts in an interactive terminal, it checks the public npm registry's latest channel for a newer version.

When an update is available, the CLI shows the installed and available versions and the exact npm command it would run. It changes a detected global npm installation only after you answer y or yes. Declining the update continues the original command.

Check immediately or install an available update explicitly:

markyard update
markyard update --yes

--yes is an explicit confirmation intended for a non-interactive agent or script. Normal non-interactive commands and commands using --json do not perform an update check.

The CLI does not automatically change a project-local or npx installation. It prints copyable npm or npx guidance for those installations. If a global update cannot be installed, rerun the exact command printed by the CLI; do not add sudo, because that can create a second installation owned by a different operating-system user.

Sign in

Connect the CLI to your Markyard hosting:

markyard --server https://markyard.example.com auth login

The CLI opens your browser so you can sign in through your organization's identity provider. After sign-in, check the saved account and server connection:

markyard auth status

The saved session is scoped to that Markyard server. Do not paste its token into a command, document, issue, chat, or agent prompt.

The CLI trusts certificates accepted by your operating system, including a corporate CA installed by your administrator. If your administrator instead gives you a PEM CA certificate or bundle that is not installed in the operating-system trust store, use it explicitly for each command:

markyard --ca-cert /path/to/company-ca.pem --server https://markyard.example.com auth login
markyard --ca-cert /path/to/company-ca.pem status

An explicit CA file replaces the operating-system trust roots for that command. The file must contain at least one PEM-encoded certificate.

Work with an existing document

Copy the document ID from its Markyard URL. For example, the document ID in https://markyard.example.com/documents/DOC_ID is DOC_ID.

Pull the document into a local Markdown file:

markyard pull DOC_ID --output proposal.md

The CLI binds proposal.md to that Markyard document and remembers the version it downloaded. Edit the file with any Markdown editor, then inspect your work:

markyard status proposal.md
markyard diff proposal.md
markyard diff proposal.md --against remote

When the changes are ready, push them to the stable document URL:

markyard push proposal.md https://markyard.example.com/documents/DOC_ID

Use the full URL shown in Markyard. A push will not send saved credentials to a different server or change the document bound to the file.

Create a document from a Markdown file

Create a new Markyard document and bind the local file in one step:

markyard create meeting-notes.md --title "Weekly meeting notes"

The command prints the new document URL. Use push for later updates; create refuses to create a second document from a file that is already bound.

Command reference

This reference covers every CLI command supported for customer hostings. Run markyard COMMAND --help to see the options provided by your installed version.

update

markyard update [--yes]

Checks the appropriate npm release channel and updates a detected global npm installation. Without --yes, an interactive terminal asks for confirmation. With --yes, the command treats its invocation as explicit confirmation. Local and npx installations are reported but are not modified.

auth login

markyard --server https://markyard.example.com auth login

Opens a browser sign-in and saves the resulting session for later CLI commands. Run it again when the session expires or when you need to connect to a different hosting.

auth status

markyard auth status

Shows the configured server, whether it is reachable, and the signed-in Markyard user.

create

markyard create FILE --title TITLE

Creates a remote document from FILE, uploads its referenced local images, and binds the file to the new document. --title is required.

pull

markyard pull DOC_ID [--output FILE] [--force]

Downloads the current Markdown and managed images. Without --output, the file is named DOC_ID.md. When a bound file also has local edits, the CLI attempts a three-way merge instead of silently replacing them.

--force replaces the local file with the remote document, can change its binding, and discards a pending conflict or edits to managed images. Use it only after confirming that no local work needs to be kept.

push

markyard push FILE DOCUMENT_URL

Uploads the Markdown and referenced local images to the explicit stable document URL. The CLI checks the remote version before writing and attempts to merge concurrent changes. It refuses to overwrite a different non-empty document from an unbound file.

There is no force-push option. Pull and review a non-empty remote document before replacing its content.

diff

markyard diff FILE
markyard diff FILE --against remote
markyard diff FILE --against remote --doc-id DOC_ID

Shows a line-by-line Markdown diff:

• the first form compares a bound file with the version recorded at its last successful synchronization;
• --against remote fetches and compares the current Markyard document; and
• --doc-id lets an unbound file be compared with a specific remote document.

--against base can be supplied explicitly when you want the first comparison.

status

markyard status
markyard status FILE

With no file, shows server reachability and all local document bindings. With a file, shows its document ID, server, and synchronization state:

Global options

Global options may be added to any command:

Resolve concurrent changes

Pull and push automatically merge changes when the same lines were not edited. If both sides changed the same content, the CLI writes standard conflict markers into the Markdown file and reports conflicted.

To resolve the conflict:

1. Open the file and find the <<<<<<<, =======, and >>>>>>> markers.
2. Edit the section so it contains the final text you want to keep.
3. Remove every conflict marker.
4. Run markyard diff FILE --against remote and markyard status FILE.
5. Push the resolved file to the same stable document URL.

Do not delete the CLI's synchronization state to clear a conflict. Use pull --force only when you intend to discard all local conflict resolution and keep the remote version.

Work with images

When Markdown references a local image, create and push upload it and update the Markdown to use a managed Markyard reference. pull downloads the managed renditions needed beside the document.

Treat downloaded renditions as managed files. To replace an image, reference a new ordinary image file in the Markdown and push again instead of editing a managed rendition.

Use the CLI with an AI agent

The Markyard CLI agent skill teaches compatible agents these commands and their safety rules. See Use Markyard with an AI agent for installation, example prompts, and recommended approval boundaries.