mdlogic
v1.2.0
Published
The command-line client for Markdown Logic. Publish Markdown and structured documents, render PDF, DOCX, HTML and EPUB, cut releases and manage share links from your terminal or CI.
Maintainers
Readme
mdlogic
The command-line client for Markdown Logic. Publish Markdown and structured documents (OpenAPI, AsyncAPI, GraphQL, JSON Schema, SBOMs, VEX, OSCAL, SARIF, FedRAMP, BPMN, DMN, ReqIF) from your terminal or CI. It can also render PDF, DOCX, HTML and EPUB, cut releases, manage document history and create share links.
1.2.0 release candidate (unpublished). The current published stable package remains 1.1.1. This candidate includes the later format and rendering-option fixes. It must pass exact-tarball qualification before publication; installing 1.1.1 does not install this candidate.
- It needs Node 22, 24 or 26.
- One runtime dependency (
picocolors, pinned, with no dependencies of its own). This tool holds OAuth credentials and often runs unattended in CI, so its dependency tree is kept to one small, auditable package.
See the release notes and migration guidance before upgrading automation.
Install
npm install -g [email protected]
mdlogic --versionTo run a command without installing anything, use npx:
npx [email protected] --helpGet credentials
- Sign up at markdownlogic.com.
- In the app, open the account menu → API keys and choose New API key. Keep the four things ticked under What it can do (Read documents, Change documents and projects, See teams and projects, Read releases) and choose Create key. Copy the client ID and the secret; the secret is shown only once.
- Sign in:
mdlogic login --client-id <id> --client-secret <secret>
mdlogic whoamiA key made in the app covers documents, projects and releases. login prints a note that the key is narrower than the CLI asked for. That is expected. The only thing it withholds is the mdlogic oauth-client commands, which manage keys and need the access-keys:manage scope. If you want those too, create the key with mdlogic oauth-client create from a session that already has it.
Quick start
mdlogic project create my-docs # create a project (a new account has none)
mdlogic project list # or list the projects you already have
mdlogic use <projectId> # default project for later commands
mdlogic publish docs/guide.md # lands at docs/guide.md in the project
mdlogic doc list --json # copy the stable document ID
mdlogic render <documentId> --format pdf --out guide.pdf
mdlogic share create <documentId> # prints a share linkmdlogic --help lists every command, and mdlogic help <command> shows one in detail.
Import an office document
mdlogic import report.docx --folder reports --json
mdlogic import report.pdf --name reviewed-report.mdimport converts one PDF, Word, OpenDocument, Excel or Numbers file to Markdown. Uploads can be at most 10 MB; scanned documents without text are unsupported. Review the converted Markdown and warnings before sharing it. The JSON result includes the stored document's stable artifact.id, display version and guarded-write revision.
An identical re-import returns the existing document without a new version. When a default name is taken by different content, the API chooses a numbered name and the CLI reports it. An explicit --name refuses a collision with different content. Import never replaces a document; use doc update with its observed revision after reviewing the converted source.
For a ZIP archive, open the project's Import action in the web app. Its review flow preserves text paths and folders and asks you to resolve collisions before committing items. mdlogic import handles individual office files and PDFs; it does not extract archives. For a local Markdown or structured text file, use publish or doc create.
Import a public page
Page import creates a review candidate. It supports one public HTTPS page, including JavaScript-rendered text; it does not crawl, monitor, sign in or bypass paywalls.
mdlogic page-import https://example.com/guide --request-id <uuid> --json > candidate.json
# Review candidate.preview.content, save it in reviewed.md, and edit it as needed.
mdlogic page-save <previewId> reviewed.md --name guide.md
mdlogic page-source <documentId> --json
mdlogic page-refresh <documentId> --request-id <new-uuid> --json
# Compare the candidate with `mdlogic doc get <documentId> --json` before replacing.
mdlogic page-save <previewId> reviewed.md --name guide.md --mode replace \
--expected-id <documentId> --expected-revision <reviewed-revision>
mdlogic page-usage --jsonPreviews expire after 30 minutes. Saving a new copy is the default. Replacement is explicit and requires both the stable ID and reviewed revision; a concurrent change is refused. A failed or uncertain refresh preserves the saved document. Source provenance distinguishes the snapshot applied to the document from the latest successful retrieval. Remote image references remain in Markdown but are never fetched for preview or export.
The server enforces a 24-hour source cooldown and shared monthly team allowances: Free 10, Personal 150, Professional, Team and Open Source 500. Each successfully returned import or refresh preview counts once even when discarded. Saving, saving a copy and replaying the same request do not consume another retrieval. Failed retrievals release their reservation but remain subject to retry and abuse limits. Allowances reset at the UTC calendar-month boundary; existing document quotas apply at save.
Page retrieval requests are not automatically retried. Reuse --request-id after an uncertain response; generated keys are included as error.details.pageRequestId on failure. After a confirmed extraction failure, follow the server’s retry time and use a new request key for a new attempt. Never remove revision guards to get past a conflict. Cloudflare Browser Run processes the public URL and page in a fresh private session; see the page-import guide and Privacy Policy.
Authenticate
mdlogic login --client-id <id> --client-secret <secret> # exchange client credentials
mdlogic login --token <access_jwt> # store a JWT you already hold
mdlogic login --no-store ... # validate without writing config
mdlogic logout
mdlogic whoami [--json]Credentials are stored in ~/.mdlogic/config.json, readable only by you (0600, in a 0700 directory). Set MDLOGIC_CONFIG_DIR to keep it somewhere else.
Use a private directory for MDLOGIC_CONFIG_DIR; an existing custom directory keeps its caller-managed permissions. Config-file symlinks are refused. Config updates replace a complete owner-only temporary file, and logout reports a failure if credential removal fails. Serialize login, logout, use and config set: simultaneous config changes can replace each other's settings. A process killed during a write can leave a private .config.*.tmp file; remove it after the command has stopped.
Keep secrets off the command line where you can. Other processes can read argv, and shells save it in history. Share passwords are accepted only on stdin (--password-stdin), and config get/config set refuse the token key. Three flags do still take a secret on argv: login --token, login --client-secret and the global --key. Where possible, use the MDLOGIC_CLIENT_ID + MDLOGIC_CLIENT_SECRET (or MDLOGIC_TOKEN) environment variables instead. A credential supplied that way is used for the run and never written to disk.
Credential profiles
Several accounts or teams can be signed in side by side as named profiles:
mdlogic login --client-id <id> --client-secret <secret> --profile work
mdlogic login --token <jwt> --profile personal
mdlogic --profile personal doc list
export MDLOGIC_PROFILE=workThe active profile is chosen by --profile, then MDLOGIC_PROFILE, then default. Signing in to another profile does not switch to it. mdlogic logout removes credentials from that one local profile only. It makes no server request: a copied token remains usable until expiry or server revocation. Environment variables and credentials in other profiles are unaffected. To withdraw server access, revoke the relevant token or API client through the supported account/API controls; deleting local config is not server revocation.
Commands
mdlogic login [--token <jwt> | --client-id <id> --client-secret <secret>] [--no-store]
mdlogic logout
mdlogic whoami [--json]
mdlogic use <projectId> # set the default project for this profile
mdlogic config get <apiOrigin|teamId|projectId>
mdlogic config set <apiOrigin|teamId|projectId> <value>
mdlogic config list # effective config; never prints the token
mdlogic completion bash|zsh|fish # shell completion script
mdlogic team list
mdlogic team usage [--team <id>] # plan + how close each limit is
mdlogic project list [--team <id>]
mdlogic project create <name> [--mode document|software] [--team <id>]
mdlogic project share create [--template file-library|support-site] [--accent-color '#174ea6'] [--background-color '#f5f6f8'] [--welcome <text>] [--acknowledge-sensitive]
mdlogic project share list
mdlogic project share update <shareId> [--template file-library|support-site] [--accent-color <hex>] [--background-color <hex>] [--welcome <text>]
mdlogic project share revoke <shareId>
mdlogic publish <file> [--project <id>] [--name <path>] [--format <format>]
mdlogic publish <file> --expected-id <documentId> --expected-revision <revision> [--name <path>] # explicit captured replacement
[--snapshot | --release <semver>] [--branch <name>] [--commit <sha>] [--build <id>]
mdlogic import <file> [--project <id>] [--name <name>] [--folder <folder>] # Word, PDF or office file to a Markdown document
mdlogic page-import <url> [--request-id <uuid>]
mdlogic page-refresh <documentId> [--request-id <uuid>]
mdlogic page-save <previewId> <file> --name <name> [--mode create|replace]
[--expected-id <documentId> --expected-revision <revision>]
mdlogic page-source <documentId>
mdlogic page-usage
mdlogic releases list [--project <id>] [--kind release|snapshot]
mdlogic releases latest [--project <id>]
mdlogic doc list [--project <id>] [--status active|archived|all]
mdlogic doc create <file> [--name <path>] [--format <format>] [--project <id>]
mdlogic doc update <documentId> <file> --expected-revision <revision> [--format <format>] [--project <id>]
mdlogic doc get <documentId> [--version <versionId>] [--project <id>] # live, or historical (paid plans)
mdlogic doc archive <documentId> --expected-revision <revision> [--project <id>] # drops out of the active list; restorable
mdlogic doc restore <documentId> --expected-revision <revision> [--project <id>]
mdlogic doc rename <documentId> <newName> --expected-revision <revision> [--project <id>] # same folder; refused if the name is taken
mdlogic doc delete <documentId> --expected-revision <revision> [--yes|-y] [--project <id>] # permanent; owner/admin only
mdlogic doc share <documentId> [--expires-in 30|60|90|365|never] [--name <name>] [--password-stdin] # alias for `share create`
mdlogic search <query...> [--scope project|team|repo] [--repo <id>] [--limit <1-50>] [--mode auto|keyword|semantic] [--kinds <list>] [--max-wait <s>]
mdlogic share create <documentId> [--expires-in 30|60|90|365|never] [--name <name>] [--password-stdin]
mdlogic share list <documentId>
mdlogic share revoke <shareId>
mdlogic share check <name> # is this share name available?
mdlogic versions list <documentId> # history, newest first (paid plans)
mdlogic versions show <documentId> <versionId> # a historical version's content (paid plans)
mdlogic versions restore <documentId> <versionId> --file <original-restore.json> # Properties-enabled document (paid plans)
mdlogic versions restore <documentId> <versionId> --expected-revision <revision> # explicitly Properties-inactive document only
mdlogic render <documentId> [--format pdf|docx|html|epub|md] [--out <file>]
[--detail summary|full] [--opt key=value ...] [--variables raw|resolved] [--if-changed]
mdlogic render options [--format <format> | --document <documentId>] # what --opt/--detail each format supports
mdlogic oauth-client create <name> [--team <id>] [--grant-types ...] [--scopes ...] [--redirect-uris ...] [--description ...]
mdlogic oauth-client list
mdlogic oauth-client revoke <clientId>
Global: --json | --quiet | --api-origin <url> | --team <id> | --project <id> | --key <jwt> | --profile <name> | -h/--help | -v/--versionProject commands require projects:read in addition to their document or release scopes. The CLI validates a supplied, saved or environment project against the selected team’s full authorized project list, including archived projects, before accessing that project. A missing or incompatible ID returns PROJECT_NOT_IN_TEAM; it makes no document request. If the project-list read is denied, its original error is preserved. --team does not change the saved project: provide a matching --project or use another profile. use stores a choice locally; validation happens when a project command runs.
If your account has one team and one active project, you can usually leave out --team and --project. mdlogic use <projectId> stores a default project per profile, and MDLOGIC_TEAM / MDLOGIC_PROJECT set defaults for CI.
Document identity and guarded updates
File commands take the stable documentId returned by doc list, doc create or publish. Paths remain destinations for creation and CI publishing. Duplicate filenames in different folders have different IDs; renaming or reusing a path does not change which document an ID targets.
doc get <documentId> --json returns a string display version and a separate revision fingerprint. A missing stored version displays as "1"; reading it does not change stored data. Pass the observed revision to update, rename, archive, unarchive or delete with --expected-revision. Historical version restore uses the original operation file for a Properties-enabled document; --expected-revision alone is retained only for an explicitly inactive document. See Historical restore. A conflict is refused without an automatic retry: read again, review the intervening change, then decide whether to submit another update. doc create and publish refuse an existing path by default. For an explicit automation replacement, publish requires both --expected-id and --expected-revision from a prior read; the destination must still identify that captured document. A missing document cannot turn replacement authority into creation. The CLI never fetches a new revision merely to write.
Migrating from earlier betas
Earlier published betas accepted document paths and implicitly replaced documents when publishing to an existing path. This source requires stable IDs for existing documents and observed revisions for writes. Read doc list --json to choose the ID, then doc get <documentId> --json to capture its revision. Keep paths for creation destinations only. A display version is not a write revision, and a historical version ID is a separate value from both.
Replace doc get guide.md with doc get <documentId>, and supply --expected-revision <reviewed-revision> to update, rename, archive, unarchive or delete. Repeated publish guide.md now refuses a collision; an intended replacement needs both --expected-id and --expected-revision. Profiles, MDLOGIC_* variables and the config location retain their names; a legacy flat config is read without rewriting and migrated when settings are next saved. Review automation before upgrading.
Historical restore
For a Properties-enabled document, read doc properties get <documentId> --json and doc get <documentId> --json. Capture the advertised epoch.idempotencyEpoch, the current head's versionId and the document's current revision. Save this original operation as original-restore.json, replacing every placeholder before submission:
{
"idempotencyEpoch": "EPOCH_FROM_PROPERTY_SNAPSHOT",
"idempotencyKey": "YOUR_UNIQUE_OPERATION_KEY",
"expectedHeadVersionId": "CURRENT_HEAD_VERSION_ID",
"expectedRevision": "CURRENT_DOCUMENT_REVISION"
}mdlogic versions restore DOCUMENT_ID HISTORICAL_VERSION_ID --file original-restore.json --jsonThe file has exactly these four nonempty string fields and a 40 KiB limit. After an uncertain response, keep its bytes and both target IDs unchanged. The CLI does not refresh authority, retry automatically or fall back to an unkeyed request. A conflict requires reviewing current state before preparing a new operation. --file and --expected-revision are mutually exclusive; revision-only restore is supported solely for explicitly Properties-inactive documents. doc restore unarchives a document; historical restore creates a new version, with a receipt for a Properties-enabled document.
Publishing
mdlogic publish <file> in this source checkout accepts fourteen explicit content formats: markdown, openapi, asyncapi, graphql, json-schema, cyclonedx, spdx, vex, oscal, sarif, fedramp, bpmn, dmn and reqif. The format is detected from the file's content, not its name. Pass --format <id> to pin it.
The published 1.1.1 package accepts only the first eleven IDs as explicit --format values. For BPMN, DMN or ReqIF XML on a server that supports those formats, omit --format so the server can detect the content. Do not use the three new explicit flags with 1.1.1.
mdlogic publish guides/api/auth.md publishes to guides/api/auth.md inside the project, creating folders as needed. --name picks a different destination. An absolute path, or one containing .., publishes under the file's name alone.
For replacement, first inspect mdlogic doc get <documentId> --json, review its source and revision, then submit the intended complete source with the captured ID and revision:
mdlogic publish guides/api/auth.md --expected-id <documentId> --expected-revision <revision>A concurrent write, rename, archive or reused path is refused. There is no force flag or automatic retry. mdlogic doc update <documentId> <file> --expected-revision <revision> also updates the captured document by stable ID.
A document is sent as text inside a JSON request. The API caps the complete request at 2,000,000 bytes (about 1.9 MiB). The CLI checks the JSON-encoded content against that cap before uploading; request metadata also consumes part of the server’s budget. Quotes and newlines can grow when escaped, so a file can be under the limit on disk and over it on the wire. Invalid UTF-8 and empty files are refused. page-save separately limits reviewed Markdown to 1,000,000 bytes on disk.
The CLI reports the path it actually stored, which may differ from the one you asked for: a document path allows a narrower set of characters, so my notes.md is stored as my-notes.md. If the content fails validation for its format, it's stored anyway with a warning, and renders may be incomplete until it's fixed:
published specs/orders.yaml (create) as openapi
warning: invalid openapi: missing required field "info.version"
It was stored anyway; renders may be incomplete.--snapshot and --release <semver> freeze the project's current documents, so publish everything else first, and pass only one of the two. Releases need a project created with --mode software; every plan can make them. If the release itself is refused, for example because of the wrong project mode or a version that already exists, the CLI says so and says the document was published, because the upload happens first.
Rendering
mdlogic render options # every format's --opt keys and --detail behavior
mdlogic render options --format openapi --json # this source checkout filters JSON as well as human output
mdlogic render <documentId> --format html --detail full --opt deprecated=hide --out orders.html
mdlogic render <documentId> --format html --if-changed --out orders.html
mdlogic render <documentId> --format md --variables raw # -> <documentId>.rendered.md- With no
--out, output uses a sanitized document ID plus the format extension (<documentId>.pdf, or<documentId>.rendered.mdfor Markdown). Pass--outwhen you want a specific filename. - A render is never written through a symbolic link at the output file or its
.etagfile. With no--out, the output also has to stay inside the current directory: if a folder on the way is a link to somewhere outside it, the render is refused. A folder you name in--outis used as given. - Regular render files and sidecars are replaced from complete owner-only temporary files (
0600on POSIX). If the command is interrupted before replacement, the previous output remains. A private.<filename>.*.tmpcan remain after a hard kill; remove it after the command stops. The output and sidecar are separate writes; concurrent renders may invalidate the fingerprint and require a full download next time. --out /dev/stdout(or/dev/fd/1) writes only document bytes to standard output; its human summary goes to stderr. Add--quietto suppress that summary. No.etagfile is kept for a stream:mdlogic render <documentId> --quiet --out /dev/stdout | lpr.--format mddownloads the Markdown snapshot.--variables raw|resolvedchooses whether%VARIABLES%are substituted (the default isresolved). Its default file name is<documentId>.rendered.md, so it never overwrites your source file.--detail summary|fullswitches between the concise and the detailed view of a structured format.--opt key=valueis repeatable and format-specific, such as--opt deprecated=hideon an OpenAPI description. Runmdlogic render optionsto see what each format supports;render options --formattakes a content format (openapi), not an output format (pdf). A multi-select option takes a comma-separated list:--opt sdrSections=indicators,requirements.- Every render writes a
<out>.etagfile next to the output. On the next run,--if-changedskips the download if neither the server's render nor your local file has changed, so it's safe to run from every build. Add*.etagto your.gitignore.
For saved-document choices (for example, the packages actually present in an SBOM):
mdlogic render options --document <documentId> --project <projectId>
mdlogic render options --document <documentId> --project <projectId> --json
mdlogic render <documentId> --format pdf --opt vulnerabilities=show --out sbom.pdfDocument discovery requires authentication and validates the selected project in its team. It preserves the full server response in JSON, including saved/effective settings and coverage metadata. Human output includes source labels and applicability metadata. Use --format or --document, not both. Global format discovery remains public.
Rendering with --opt or --detail validates against the saved document's options, including document-specific multi-select choices. If discovery fails, the command stops without exporting rather than silently substituting defaults. Duplicate keys and invalid values are refused. These are per-export overrides, not changes to saved document settings. Embedded SBOM vulnerabilities are source-reported findings, not a new vulnerability scan.
Searching
mdlogic search rotate the signing key # the default project; several words are one phrase
mdlogic search "rate limit" --scope team --kinds repo_doc # every project and connected repository the team has
mdlogic search deploy --scope repo --repo <repoId> # one connected repository
mdlogic search "webhook retries" --limit 5 --json | jq '.results[].document.path'
mdlogic search "release notes" --max-wait 60 # in CI: wait out a rate limit of up to a minuteSearch reads the content of your documents, not only their names, and prints each match with the first passage it came from (long passages are cut and end in …; --json carries them whole). Several words after search are joined into one query, so quoting is optional. --scope project (the default) searches the project --project or your profile names; --scope team searches every project and connected repository; --scope repo --repo <id> searches one connected repository. --mode keyword matches words, --mode semantic matches meaning, and auto lets the server choose. Results that were edited a moment ago may be missing while the index catches up; the output says so when that is the case. Search requires a plan that includes it.
Searches are budgeted per signed-in account across every client at once (the app, the CLI, and assistants over MCP), so a script that searches in a loop is refused with a 429. The CLI waits out one refusal of up to --max-wait seconds (default 10, at most 300) and retries once; a longer wait is printed, rounded to minutes, and the command exits 1 like every other failure. An API key or an assistant has its own hourly allowance, separate from the one the app uses, so a job cannot lock the person out of search in the app; the per-minute allowance is shared. A search is not a way to list documents; use mdlogic doc list for that.
Sharing
mdlogic share create <documentId> # anonymous link, no password
mdlogic share create <documentId> --name product-readme # memorable name (paid plans)
mdlogic share create <documentId> --password-stdin <<< "$PASSWORD" # password-protected (paid plans)
mdlogic share list <documentId>
mdlogic share revoke <shareId>New document links default to 30 days. Set --expires-in 60, 90, 365 (one year), or never.
Durations are elapsed 24-hour days. Never links have expiresAt: null, remain revocable, and
obey document access and team sharing policy. Existing links keep their expiry.
share list pages through unrevoked links for the captured document ID. Expired links retain their expiry metadata; revoked links drop out of this list.
Share the whole project with a File library or Support site layout:
mdlogic project share create --project <id> --template support-site --accent-color '#176b45' --welcome 'Welcome to our guides'
mdlogic project share list --project <id> --json
mdlogic project share update <shareId> --project <id> --background-color '#f7faf8'
mdlogic project share update <shareId> --project <id> --welcome '' # clear the welcome message
mdlogic project share revoke <shareId>Project sharing uses the configured default project or --project <id>. New links default to file-library; both layouts, colors and welcome text are available on free plans. Colors must be six-digit hex values (quote #... in your shell), and welcome text is limited to 500 characters. Create and update print the share ID, URL and style; --json returns full share metadata and presentation settings. Update requires at least one presentation option, preserves unspecified settings (including settings previously chosen in the app), and keeps the same URL. Project share lists retain expired and revoked links with their expiry and status. Revoke needs only the share ID. --acknowledge-sensitive records acknowledgement when creating a link; any sensitive-content warning returned by the server appears on stderr.
Renaming documents
mdlogic doc rename <documentId> <newName> --expected-revision <revision> renames a document inside its folder and keeps its history. The new name is a bare file name with no folder, and it is refused if a document or folder already uses that name, ignoring letter case. Links in other documents are not rewritten, and publishing to the old name later creates a new document.
Deleting documents
mdlogic doc delete <documentId> --expected-revision <revision> asks for confirmation in an interactive terminal, and the answer has to be the word yes. Where there is no terminal to ask at (a pipeline, a CI job, or --json), it never prompts and refuses unless you pass --yes (or -y). Deletion is permanent; doc archive and doc restore are the reversible alternative.
CI/CD
Store the key's client ID and secret as masked CI variables and skip login. Each command then exchanges them for a fresh token, with no config file and nothing to expire:
export MDLOGIC_CLIENT_ID="$CI_MDLOGIC_CLIENT_ID"
export MDLOGIC_CLIENT_SECRET="$CI_MDLOGIC_CLIENT_SECRET"
export MDLOGIC_TEAM="$CI_MDLOGIC_TEAM"
export MDLOGIC_PROJECT="$CI_MDLOGIC_PROJECT"
# For previously reviewed existing documents; obtain IDs/revisions with doc list/get --json.
mdlogic publish openapi.yaml --expected-id "$OPENAPI_ID" --expected-revision "$OPENAPI_REVISION"
mdlogic publish CHANGELOG.md --expected-id "$CHANGELOG_ID" --expected-revision "$CHANGELOG_REVISION" --release "$CI_COMMIT_TAG"For a new path, omit both replacement guards. Existing paths require both; a conflict needs review, never a revision refresh solely to force the write. The release command runs last so it captures the documents already stored in the software-mode project.
A key made in the app can reach every team you belong to. To restrict a CI key to one team, create it from a session that has the access-keys:manage scope with mdlogic oauth-client create ci --team <teamId>. The credential then works in that team only, for its whole life.
Branch, commit and build metadata are read from the variables these systems set themselves: GitLab CI (CI_COMMIT_BRANCH, CI_COMMIT_SHA, CI_PIPELINE_ID), GitHub Actions (GITHUB_REF/GITHUB_HEAD_REF, GITHUB_SHA, GITHUB_RUN_ID) and CircleCI (CIRCLE_BRANCH, CIRCLE_SHA1, CIRCLE_BUILD_NUM). The flags --branch <name>, --commit <sha>, --build <id> override them. A tag build reports no branch, since a tag is not one. On another runner, set MDLOGIC_BRANCH, MDLOGIC_COMMIT and MDLOGIC_BUILD yourself.
Failures exit non-zero with an error: line on stderr. With --json, the error is {"error":{"message","code","status","details","requestId"}}. That includes local problems, where code is the system error (ENOENT).
Shell completion
echo 'eval "$(mdlogic completion bash)"' >> ~/.bashrc
echo 'eval "$(mdlogic completion zsh)"' >> ~/.zshrc
mdlogic completion fish > ~/.config/fish/completions/mdlogic.fishUpgrading and removing
npm install -g [email protected] # install the published stable version
npm uninstall -g mdlogic # remove the command
rm -rf ~/.mdlogic # and the stored credentials, if you are doneTroubleshooting
| What you see | What it means |
| --- | --- |
| Please sign in. (401) | You have no credential, or it was rejected. The message names what to fix: a stored token (mdlogic login), MDLOGIC_TOKEN, or --key. An MDLOGIC_TOKEN in your environment overrides anything login stores. |
| The authorization server rejected these client credentials | The id or secret is wrong, or the key was revoked. Secrets are shown only once, so make a new API key if you lost it. |
| This team has no projects. | Run mdlogic project create <name> first. |
| PROJECT_NOT_IN_TEAM | The selected project is not available in the selected team. Run mdlogic project list --team <teamId> --json, then pass a matching --team and --project. |
| Multiple teams found. Pass --team <id> … | You belong to more than one team; the message lists them. Pass --team <id>, or set MDLOGIC_TEAM. |
| The … plan does not include … | This feature needs a paid plan: version history, a named share or a share password. mdlogic team usage shows the plan and how close each limit is. |
| … must use https:// | The API origin and OAuth issuer take https only, because your credentials go to them. http is allowed for localhost. |
| … is not valid UTF-8 text | Documents are text; this file looks binary. |
| A command hangs | Requests time out after 15 s (30 s for renders). If a proxy sits in between, check mdlogic config list for the origin in use. |
Support
Email [email protected]. Include the command you ran, the full error, and the requestId from a --json error if you have one. It identifies the exact request in the logs.
Configuration reference
| Variable | Flag | Purpose |
| --- | --- | --- |
| MDLOGIC_CLIENT_ID + MDLOGIC_CLIENT_SECRET | | Client credentials, read from the environment only and never stored |
| MDLOGIC_TOKEN | --key | An access token for this run (takes precedence over a stored one) |
| MDLOGIC_PROFILE | --profile | Which stored profile to use |
| MDLOGIC_TEAM / MDLOGIC_PROJECT | --team / --project | Default team and project |
| MDLOGIC_BRANCH / MDLOGIC_COMMIT / MDLOGIC_BUILD | --branch / --commit / --build | Release metadata |
| MDLOGIC_CONFIG_DIR | | Where config.json lives (default ~/.mdlogic) |
| MDLOGIC_API_ORIGIN | --api-origin | API URL (default https://api.markdownlogic.com) |
| MDLOGIC_OAUTH_ISSUER | | Authorization server (default https://auth.markdownlogic.com) |
The API and authorization-server URLs must use https://, because your credentials are sent to them. Plain http:// is accepted only for localhost.
MDLOGIC_BRANCH, MDLOGIC_COMMIT and MDLOGIC_BUILD are read on any runner, and win over a CI system's own variables.
Network behavior: requests time out after 15 s (30 s for render downloads, 45 s for page retrievals). Reads are retried with backoff on 429, 5xx and network errors, honoring Retry-After. Writes are not automatically retried after network errors, 429, 5xx or 423 refusals. When client credentials are configured, a 401 can trigger one fresh token exchange and resubmission; original-operation version restores remain single-attempt, including authentication refusals. List commands fetch every page before printing.
During an Advanced Data Protection enable/disable conversion or blocked transition, ordinary content changes return HTTP 423, code CONTENT_TEMPORARILY_READ_ONLY, with details.retryable: true. The command exits nonzero and preserves your local input. Wait for conversion to complete, then deliberately retry after reviewing the current document state and any conflict. Do not drop revision guards. After an uncertain result for a property change or version restore, keep the original operation file, identity and target unchanged and use its documented recovery procedure.
Content reads continue through the server's authorized ordinary/protected read path; the CLI does not decrypt locally or bypass a read refusal. mdlogic doc get DOCUMENT_ID --metadata --json can return { "projectId": "…", "documentId": "…", "availability": "inactive", "reason": "data-protection-conversion" } while a cold property baseline is deferred. This is a successful metadata read, with no head/revision tokens. Check availability before using those fields and read metadata again after conversion. Initialized metadata retains its normal shape.
API and OAuth redirects are refused, including redirects to another HTTPS host. Configure the canonical origin directly. Office/PDF import has a 120 s deadline. API request headers and response bodies have separately bounded waits; the OAuth exchange has one 15 s budget covering both headers and body.
Known limits
The CLI renders current document content. Frozen publication source/renders remain REST API capabilities; the CLI’s
sharecommands manage document shares, andproject sharemanages project links.Every project command first lists the selected team’s projects to validate its target. Custom tokens limited to
documents:read/documents:writealso needprojects:read; a refusal never falls through to the document operation. Server permissions and plan checks still apply.With no chosen project, automatic selection considers active projects only. Explicit archived projects are validated with
status=all; server restrictions on archived-project writes remain in force.With
--json, validation, command/API and unexpected errors use the five-field JSON error envelope on stderr. A token used as an option value or after--does not select JSON output mode.Binary streaming to
/dev/stdoutor/dev/fd/1refuses--jsonbefore requesting a render. Choose a regular output file when you need JSON metadata.--quietkeeps raw document content and explicit JSON results, but suppresses other human-readable output.The prior 1.0.0 assessment covered macOS arm64 and Linux arm64. Its archived evidence reports macOS Node 22.23.3, 24.22.1 and 26.11.0, plus Linux Node 22.23.3 (glibc), 24.21.0 (glibc) and 24.22.0 (musl), using installed tarballs. Node 26 on Linux, Windows, x64 and other runtime/platform combinations are not qualified by that assessment. This source checkout still requires qualification of its final versioned tarball before publication; focused source checks do not qualify an installed release. The package accepts Node majors 22, 24 and 26; installation eligibility is broader than this tested matrix. Node 20 is outside the supported runtime floor.
The 1.1.1 installed package was qualified on macOS arm64 with Node 22.23.4, 24.19.0 and 26.12.1 on October 29, 2026, using offline clean installs and synthetic localhost API/OAuth. The complete CLI suite, including native D1/Auth/API regressions, ran on Node 26.12.1. Linux arm64 glibc/musl results from the earlier 1.0.0 assessment are historical; Linux was unavailable for this candidate because the local Docker daemon was not running. Linux, Windows, x64 and other combinations are not qualified for 1.1.1 by this preparation. The package accepts Node majors 22, 24 and 26; installation eligibility is broader than the tested matrix. Node 20 is outside the supported runtime floor.
Document properties
Add a name and text value by preparing a change, reviewing the saved file, and applying it:
mdlogic doc properties prepare DOCUMENT_ID --name status --value reviewed --out status-change.json
mdlogic doc properties update DOCUMENT_ID --file status-change.json
mdlogic doc properties get DOCUMENT_IDprepare reads once and creates a new operation file; it never sends a property edit or overwrites an existing file. Use its printed apply command to keep the resolved project and target. Values are exact text: 001, false, null, [1] and empty text stay text. Existing non-text values require --replace-type to deliberately replace them with text; native typed JSON patch files remain supported. Use --remove status to prepare a removal, or --version VERSION_ID to prepare and apply a change for one exact version.
Human output shows named values and short outcomes. Add --technical for IDs, revisions and original receipts; --json keeps the existing full machine payloads. History uses --offset for more and --offset 0 to refresh. After a conflict, review current values and prepare a new file. If a response is uncertain, retry the original file and target unchanged.
For native typed values, read the property snapshot and save the advertised epoch and annotation revision in a patch file. This example preserves booleans and numbers as native values:
{
"idempotencyEpoch": "EPOCH_FROM_SNAPSHOT",
"idempotencyKey": "YOUR_UNIQUE_OPERATION_KEY",
"expectedAnnotationsRevision": "ANNOTATION_REVISION_FROM_SNAPSHOT",
"custom": { "set": { "status": "reviewed", "score": 0, "needsWork": false } }
}Apply with doc properties update DOCUMENT_ID --file patch.json. For version metadata, use expectedMetadataRevision instead and pass the exact --version VERSION_ID to both read and update. custom.remove removes a name; setting null retains it with a null value. Availability requires a qualified deployment, allocation and enabled policy. Unavailable does not mean an empty property map.
Read first and put the returned epoch and matching revision token in the patch. Reuse the original file and exact target after an uncertain response. Reclamation requires current owner/admin and history authority; it accepts annotationRevisionIds/metadataRevisionIds, at most 100 total, and rejects protected references.
Property write responses preserve the complete server envelope in --json output,
including receipt and optional sibling serviceGuidance. Human guidance is bounded
and terminal-escaped on stderr after response validation; --quiet suppresses it.
Guidance never changes the immutable receipt or authorizes a retry. Retain the exact
original operation file and target after a lost response or throttle. A supplied
Retry-After is actual server timing; unavailable enforcement and capacity refusals
do not invent a wait.
doc list --property-filter requires an explicit scope (annotations or
currentVersion). Annotations support custom; current-version results support
custom or extracted. Keys are literal and scalar equality is type-sensitive.
Filtered live pages expose captured propertyMatch tokens, not private values.
Only limit (1–50) and offset (0–10000) may accompany this filter; later pages may
shift as documents change.
License
Proprietary. © Lemuridae Labs. All rights reserved.
