The docly CLI Last updated: 23. Oct 2026
docly is the command-line client for Docly. It gives you a local working copy you can diff before anything goes live, and commands that act directly on the server: read, search, write, publish and read the logs. Run docly with no arguments for the complete, always-current list of arguments and flags.
Install and update
docly is a single, self-contained docly.exe for Windows x64 — no .NET or other runtime to install, and no administrator rights. Download it from the Docly cloud portal under Services → Docly CLI (cloud.docly.net/cli). The page is there for accounts with developer access; no menu item means the account lacks that access.
Unblock the ZIP before you extract it — right-click
docly-win-x64.zip, Properties, tick Unblock, OK. Windows marks downloaded files, and the mark follows every extracted file; left in place it shows up as a security warning that looks like a broken package.Extract it and run
Installer Docly CLI.cmd. It copiesdocly.exeto%LOCALAPPDATA%\Programs\Doclyand adds that folder to your own PATH. Nothing is written outside your user profile.Open a new terminal — one that was already open does not see the new PATH — and check with
docly --version.
The download page shows a SHA-256 checksum. Compare it with certutil -hashfile docly-win-x64.zip SHA256.
Updating. docly checks for a newer version at most once a day and prints a notice on stderr, after the command you ran. docly update downloads the new version, verifies its size and SHA-256 and replaces docly.exe. It never updates by itself and asks before replacing anything; --yes answers for you. In a script or an agent session, where there is no terminal to ask in, --yes is required — without it the update is refused. Set DOCLY_NO_UPDATE_CHECK=1 to turn the check off.
docly --version
docly update # asks before replacing docly.exe
docly update --yes # for scriptsSign in
docly login opens the browser, where you sign in to the Docly cloud with two-factor authentication. The cloud routes every command to the Docly instance that hosts the folder, so one session reaches all your workspaces and you never switch sessions to reach another site.
docly login # through the Docly cloud (the normal case)
docly login https://docly.net --direct # one instance only
docly login https://docly.net --classic # e-mail and password instead of the browser
docly logoutThe session belongs to a directory, like
.git. It is stored in.doclycli/credentials.jsonin the directory you randocly loginfrom, andloginprints where. A command uses the nearest.doclycliabove where it runs that has a session. There is no global fallback: your home directory never takes part, so a sibling directory answers «Not logged in»..doclycli/.gitignoreis written for you and excludescredentials.json— it is a live session token.--direct(orDOCLY_DIRECT=1) signs in to one instance and reaches only the workspaces hosted there.--classicalways signs in directly.The
Serverline indocly statussays where the folder lives, not where you should sign in.
Referring to folders and documents
Every command that takes a <reference> accepts:
a path from the instance root, starting with
/— the formdocly sitesanddocly findprint, for example/example.com/assets/site.cssa guid (22 characters), as printed by
docly dir,docly findand the other commandsan id with an F (folder) or D (document) prefix, as it appears in a Docly URL
0for your home folder
Numeric ids are not accepted. Git Bash rewrites an argument that starts with / into a Windows path before docly sees it; set MSYS_NO_PATHCONV=1 or leave out the leading slash. Quote paths that contain spaces.
Commands
One line each. docly <command> --help prints the arguments and flags for one command, and a command run without a required argument prints its full signature.
The working copy — local files, nothing is live until push:
Command | What it does |
|---|---|
| Download a folder tree into a new working copy. Without a folder you browse the tree interactively. |
| List local changes. |
| Line-level diff between your files and the server. |
| Fetch server changes. A file changed both locally and on the server is skipped and listed; |
| Upload local changes. |
Write access:
Command | What it does |
|---|---|
| Open one folder, and everything below it, for writing. Without a folder: show what is open, checked against the server. |
| Refuse all writing again, locally and on the server. Needs no sign-in. |
Reading on the server — free, never needs an unlock:
Command | What it does |
|---|---|
| List a folder (blank = home). |
| Print a document's file content, or save it with |
| Server-side search under a folder. |
| List the versions of a document; |
| Who a folder or document is shared with, including pending invitations. |
| Publications on a folder ( |
| Every published site you can see and the folder it comes from. Filter with |
| The site console — |
| The system log: requests, sign-ins, errors. |
| Background jobs (copying, deleting, unzipping, package installs). With a job id: its status; |
Writing on the server — needs an unlock, and is live immediately, with no diff and no staging:
Command | What it does |
|---|---|
| Write one document from a file or from stdin. |
| Replace a piece of text in one document, on the server. Every occurrence is replaced and the count is printed; |
| Create a folder. |
| Move a folder or document into another folder. The target must be inside the open folder too. |
| Rename a folder or document. On a folder shared directly with you, a rename only sets an alias that you alone see, and the command says so («Alias set — only you see …»). |
| Delete a document. A folder and everything in it needs |
| Publish a folder, or update a publication with |
| Remove a publication. Both values come from |
| Copy a whole workspace on the server as a background job and print its id. The source must be unlocked. |
The tool itself: docly with no arguments prints the full reference and never waits for input; docly login, docly logout and docly update are described above.
There is no MCP command. An AI assistant connected over MCP gets its access in the browser when it connects, and docly unlock does not apply to it — see MCP - connect an AI assistant.
The working-copy workflow
docly login # once, in your project directory
docly clone /example.com site # local files in ./site
cd site
# ...edit the files...
docly status # what changed
docly diff # line by line
docly unlock /example.com # open the folder you cloned
docly push --dry-run
docly push
docly lockSaving is publishing. A pushed change is live on the next request. Documents bound to a schema that keeps versions get a new version (
docly history);.hash,.js,.cssand.htmlfiles have no history.Unlock the folder you cloned.
pushworks on the whole working copy and checks its root once; if the root is outside the open folder, the whole push is refused — including the files that were inside it.Conflicts. Before writing,
pushcompares each document's server timestamp with the one you cloned or pulled. A document changed on the server in the meantime is not pushed; it is listed under «Conflicts», anddocly pullbrings the server version in first. The check is not atomic — a change in the moment between the check and the write is not caught.A push that would replace a document is refused. When the new content does not fit the document's type (a Code File that becomes binary, an uploaded file that becomes valid JSON), the server would delete it and create a new one with a new id — shares, publications and links to the old id are lost.
pushasks the server first and stops before writing anything, listing each file as! file (Old type -> New type).--allow-replacepushes anyway.New documents are just new files. For a
.doclydocument, write the complete envelope with itsSchema; the server picks the type from the extension and content, and there is no schema flag. See Creating new docly files..doclyignorein the working copy's root keeps local files out ofstatusandpush(gitignore-style patterns)..doclycli/is always ignored.A change of upper/lower case in a file name is not pushed as a rename — the content is pushed under the server's name. Use
docly renamefor a deliberate rename.
Docly has no git service; this is the working copy. See Use a docly CLI working copy instead of git.
Writing is locked until you unlock a folder
Every write is refused until someone opens one folder for writing: put, edit, push, mv, rename, rm, mkdir, publish, unpublish and clone-workspace. Reading is always allowed, and so is push --dry-run.
docly unlock /example.com/assets # opens assets and everything below it
docly unlock # what is open, and does the server agree?
docly lock # close it againOne folder and everything below it — not a whole workspace unless you open its root. Two sibling folders do not reach each other.
It expires. The output shows when (one hour); run
docly unlockagain to open it anew.It belongs to the session it was made under. It is stored on your sign-in at the Docly cloud and in
.doclycli/unlocked.json. A differentdocly login— another agent session — does not see it, and an unlock made under a--directsession does not apply through the cloud.mvchecks the target as well,mkdirandput --createcheck the parent folder.There is no override flag, by design. A refused write means the folder is not open: open it, or stop and ask the person who decides.
For AI agents: How an AI agent should use the docly CLI — signing in and unlocking belong to the human.
Exit codes and errors worth knowing
Exit code | Meaning |
|---|---|
| Success. Also returned when |
| An error, printed as |
| Cancelled with Ctrl+C. |
Message | What it means |
|---|---|
Not logged in | Usually the wrong directory, not a missing session. Run from the directory you signed in from, or below it. |
Refusing to modify … / writing is locked | The target is outside the open folder. The message names the folder to unlock. |
No such path, or you have no access to it | Paths start at the instance root: |
'x' is deleted. It was replaced by … | The guid points at a deleted document, typically after a write changed its type. Use the new id. |
Timed out … | docly gave up waiting (100 seconds per request). The server may still have completed the write — check with |
A rejection that names a rule, a field and a line | The content scanner refused the content. It is not a permission problem: change the content, do not retry it unchanged. |
|
|
| A content search ran out of time. Search a smaller folder or add |
Output, scripts and environment
--jsonon the reading commands gives machine-readable output. Use it whenever a script or an agent acts on the result.Paged output says it is paged and prints the command for the next page. A first page is not the whole answer.
Timestamps in text output are UTC with the offset written out (
2026-10-15 07:41:02 +00:00);--from/--toindocly logread the same form.DOCLY_INSTANCE=<instance>pins which instance a call goes to — needed fordocly logon an account with workspaces on several instances. Cloud administrators read the cloud's own log withdocly log --cloud.NO_COLORor--no-colorturns colours off; redirected output is never coloured.DOCLY_NO_UPDATE_CHECK=1turns off the version check.
Related