How an AI agent should use the docly CLI

What you'll see

An AI agent is about to change a Docly site with docly, the command line client. Running docly with no arguments prints the complete reference — every command and flag, one call, never waiting for input. So this article lists no commands. It covers what the reference cannot: what to do, what to refuse, and what to verify.

Point an agent here before its first change:

Read /Guidelines/KB/How-an-AI-agent-should-use-the-docly-CLI, then run `docly`
for the command reference.

The rest is addressed to that agent.

What's actually happening

Three platform facts decide how you must behave. Every recurring failure here traces back to one of them.

1. Saving is publishing. No build, no staging, no deploy, no undo. A pushed change is live on the next request and there is no revert. The cheap check before a write is always worth taking.
2. Writing is locked; reading is free. Listing, searching, fetching a document, publication info, the site console and the system log cost nothing and cannot damage anything. Writing is refused until a human has opened one folder, on one instance, covering that folder and everything below it. A refusal is the system working, not an obstacle. There is deliberately no override flag, so looking for one — another command, the mapped drive, the API directly — is wasted effort and defeats the only control that does not depend on someone remembering an instruction. Signing in and unlocking are decisions about blast radius and belong to the site's owner, not to you.
3. State belongs to a directory, not to you. The session and the write permission live in a .doclycli directory like .git, and nothing is kept in the home directory — deliberately, so a sign-in elsewhere cannot move you to another instance. Run every command from the same directory, or from one below it — the search only ever goes upward. Sideways is a different instance, or no session at all.

What to do

If docly is not there

«command not found» is not a dead end, and not a reason to fall back on the mapped drive, a git clone or the API. The client is a download in the Docly cloud portal — Services → Docly CLI, at /cli (on docly.net: cloud.docly.net/cli) — for accounts with developer access. No menu item there means the account lacks that access, which is granted rather than worked around.

• Installing is the human's, so hand over the whole sequence at once. Open the page and download; unblock the ZIP before extracting — right-click, Properties, tick Unblock — because Windows marks downloads and the mark follows every extracted file; then extract and run «Installer Docly CLI.cmd». Left out, the unblock step returns as a security warning that reads like a broken package.
• Nothing else needs installing. The package brings its own runtime, installs into the user's own profile, needs no administrator and writes nothing outside it. Say so: this stalls most often on someone assuming a runtime, an elevation prompt or a machine-wide change is coming.
• Then start a new shell — including your own. The installer adds the folder to PATH, but a terminal that was already open keeps the environment it started with. This is the one that will fool you: the install worked, and your next command still says «not found». Start a new shell, or call it by full path: %LOCALAPPDATA%\Programs\Docly\docly.exe.
• Confirm rather than assume it landed. docly --version, compared against the version on the download page. Verifying the download is yours too, not theirs: the page shows a SHA-256, and certutil -hashfile <file> SHA256 checks the copy they were actually given.

Before the first command

1. Run docly with no arguments and read it. Do not guess a flag, do not ask a human what the commands are, do not infer one from another tool.
2. Check what is unlocked: which folder, which instance. If nothing is open, or the work is outside it, stop and ask. Do not sign in. Do not unlock.
3. Run every command from the directory the human authorized in, or from somewhere below it. The operator normally signs in and unlocks where the session was started, which is usually the project root. The lookup walks upward from where you are and stops at the first .doclycli that holds what it needs, so any subfolder inherits both the session and the open folder.
4. «Not logged in» usually means wrong directory, not missing session. A sibling folder, a temp directory or another drive is not below the authorized one and inherits nothing — and the home directory deliberately never participates, so there is no global fallback to save you. Do not sign in to fix this. Move to a directory under the authorized one, or copy the state as below.
5. Working outside that tree: copy the state, do not create a new one. Copy .doclycli/credentials.json from the authorized directory into a .doclycli in yours, plus unlocked.json if you need to write. Leave manifest.json where it is — it describes a working copy, not a session. Copying the open folder does not widen what is writable in Docly; it only carries the same permission to where you are standing. Remove the copy when you are done: credentials.json is a live session token, which is why it is gitignored where it came from.

Reading

• Never act on an assumption a read would settle. Reads cost nothing.
• Know the guid and path of everything in scope before changing anything, and confirm each is what you think it is.
• Use the server's search. Never loop a folder listing over a tree — that is thousands of requests and presents as a hang, not an error.
• Never conclude «it does not exist» from a first page. Paged output says it is paged and prints the next command. This is the most common way an agent reaches a confidently wrong conclusion here.
• Use --json whenever you will act on the output. Parsing the column-aligned form will eventually parse it wrong.

Changing

• Default: clone, edit, status, diff, show the human, push. The diff is the only way to put a change in front of someone before it is live. Show it and wait, unless told explicitly to push without review.
• Server-direct commands are live immediately — no diff, no staging. Use them for exploring, publishing, logs and cross-folder work.
• Dry-run any push or pull that is not trivially small.
• Creating a document is the one thing the reference does not make obvious. The single-document update command only updates. Create by writing the file into a working copy and pushing it with the schema named.
• Get the schema name exactly right. A name that does not match a real schema is stored verbatim, so the document binds to nothing and renders as nothing — it is not an error you will be told about. Before writing, read a sibling document in the destination folder, read the schema, and check the folder's properties for which schemas it accepts. Validate that the JSON parses. Generate it — never hand-escape rich text into a JSON string. A failed write is correctable at the same path; envelope rules and the failure shapes are in Creating new docly files.

Verifying

• After changing server-side code, read the site console — that is where console.log from hash and API code goes. Take the console reference from the publication info; do not derive it.
• Console empty and the page still wrong means the request failed before your code ran. Read the system log; it is a different log and the only place that answer exists. An empty console reads as «no errors» and means «your code did not run».
• A rendered page is not verification on its own — your browser serves cached static assets and will show you the previous version working. See Work safely on a live site.
• The site console and the browser are two halves. The site console shows what your server-side code did. It cannot see a script error, a blocked inline style, a 404 on an asset, a collapsed layout or a form that posts nothing — those exist only in the visitor's browser.

Verifying in a browser

If you can drive a browser — Claude in Chrome, or any headless driver — the other half is yours to check, not the human's. It is also the only way to see your own work the way its readers will.

• Open the page you changed and read the browser console and the network requests. Hard-reload first — the cached script that shows you the previous version working is exactly the trap above.
• Make sure the console was listening before the page loaded, or reload once it is. A capture that started late looks exactly like a clean console — the same false all-clear as the empty site console above, and easy to walk into when the browser tool starts capturing on first use.
• Exercise it, do not look at it. Submit the form, follow the link, run the search. A page that renders is not a page that works.
• Layout counts as work you can check. Do not resize the window one width at a time — put the page in a viewport harness and review every breakpoint in one pass, per Test layouts in real viewports.
• Check the admin side wherever the change reaches it — that a new document bound to its schema and opens in the editor, that publication settings are what you assumed, that the folder looks the way the owner expects. The CLI tells you what the server stored; the UI tells you what a person will see.
• Site console, browser console and system log together cover the whole path from request to pixel. Close that loop yourself before anyone else looks, and report what you actually saw.

Stop and ask before

• Deleting a folder and its contents, moving, renaming, or removing a publication.
• Moving or renaming changes the path; published URLs and links do not follow.
• Read what a push prints. A document can come back with a new id, and a recreated document loses its shares and publications. Exit code 0 is not approval.

Ask for decisions, not for legwork

The section above is what the human decides. Everything else is yours to do.

• «Can you check whether the page works now?» is not a question, it is a task handed back. Load it, click it, read the console, report the result.
• The same goes for reproducing the fault, finding the guid, reading the log, confirming the schema bound, and taking the screenshot. If a read or a page load would settle it, settle it.
• Where you genuinely cannot act, offer. Name the capability you are missing, say which parts are therefore unverified, and say what you would do with it. Never quietly downgrade to «it should work». Someone who does not know you can drive a browser will keep doing it by hand.
• The exception stays the exception: signing in, unlocking, deleting, approving a change, and installing software belong to the human however easy they would be for you.

Report

• guid and path of everything you created, changed, moved or deleted.
• The console or log output you verified against.
• Anything you broke — immediately and plainly. On a platform with no history, your report is the only record of what changed.

For the human

The prompt is not the safety mechanism. The unlock is. Open the narrowest folder that contains the work before the agent starts, and close it afterwards. Everything above stops an agent wasting turns; it is not what keeps the site safe.

Put this in the workspace's .claude/CLAUDE.md — under .claude/, never at the workspace root, which is published and served over HTTP. Point rather than teach, per Set up AI agent instruction files for a workspace:

## Changing this site

Use the `docly` CLI. Not the mapped drive, and do not `git init` anything.
Run `docly` with no arguments for the reference before guessing at a flag.

Read /Guidelines/KB/How-an-AI-agent-should-use-the-docly-CLI and follow it.
If a write is refused: STOP and ask. Do not sign in, do not unlock, do not
look for another route in.

Verify your own work: the site console and the system log with docly, and the
page itself in the browser - hard-reload, submit the form, read the browser
console. Do not ask me to check whether it works.

Three prompt shapes worth copying. Naming the search prevents the folder-listing loop:

Using docly, search <folder> for every .hash file that calls sendMail - use the
search command, not a loop of folder listings. Give me guid and path for each.
Change nothing.

The approval gate belongs in the prompt, because an unlock cannot express «ask first»:

Clone <folder> with docly. In the working copy, change X to Y. Show me the
status and the diff, and do not push until I say so.

An agent not told where the output is will report success from a page it never checked:

Fix the error in index.hash and push it. Then request the page and read the site
console with docly, and repeat until the console is clean. If the console stays
empty, read the system log for errors - the request is failing before the code
runs. Then open the page in the browser, hard-reload it, submit the form and
read the browser console too. Paste what you verified against.

Do not ask for «unlock the workspace and fix the site»: unbounded blast radius, handed to a process with no undo, on a platform where saving is publishing.