| workspace_listA | List the workspaces registered in the server's home directory. Read-only. The configured default is named separately. Registration is
administration done elsewhere; this tool never registers or removes one. |
| workspace_infoA | Describe the selected workspace, or one registered workspace by name. Read-only. Reports the workspace name, identifier, registered root and
whether the selection is a transient --root rather than a registration.
It also reports the server's own package ``version``, so a caller can
record which build it measured without running the binary.
It does not create, select or modify a workspace.
|
| file_readA | Read a text file, optionally a bounded line range. Line numbers are 1-based and inclusive. Omitting both returns from the
first line. A byte limit smaller than the range truncates honestly:
truncated, truncation_reason and next_start_line say where to resume. A
UTF-8 byte-order mark is preserved and line endings are returned exactly
as stored. Binary content is refused with BINARY_CONTENT_REFUSED unless
an encoding is named. Read-only; no history is recorded. With a
workspace rooted at the filesystem root, the reported path keeps its
leading '/' so it is exactly the absolute path.
|
| file_read_manyA | Read several text files in one call (at most 32 paths). Each entry reports its own path, ok flag, result or error; one missing
file does not hide the others. Line numbers are 1-based and inclusive and
apply to every file. The call itself is read-only. More than 32 paths is
refused with LIMIT_EXCEEDED rather than silently truncated.
|
| directory_listA | List directory entries under a workspace-relative path. Read-only. Recursion depth and entries are bounded by configuration; a
truncated listing says so instead of pretending it is complete. The
server refuses max_entries above 1000. Filekeeper's own .filekeeper/
state directory is never listed.
|
| file_infoA | Report metadata for one path, including hash, encoding and newline for text. Read-only. The content_hash is what the guarded mutating tools accept as
expected_hash. Symlink metadata describes the link, not its target. With
a workspace rooted at the filesystem root, the reported path keeps its
leading '/' so it is exactly the absolute path.
|
| file_searchA | Find workspace paths matching a glob, under one directory. Read-only. At most 200 results may be requested; a larger request is
refused with LIMIT_EXCEEDED. A truncated result says so. Literal file
names are faster with directory_list when the directory is known.
|
| content_searchA | Search file contents by literal text (default) or a regular expression. Read-only. Matches carry path, 1-based line number, column and the whole
line. At most 200 matches may be requested; a larger request is refused
with LIMIT_EXCEEDED and a truncated result says so. An invalid regular
expression is INVALID_PATTERN. Binary files are skipped.
|
| file_createA | Create a new text file and return operation_id and undo_available. Fails with ALREADY_EXISTS while expected_absent is true (the safe
default); set it false to overwrite an existing file, which makes the
call destructive. Writes are atomic. Credential-shaped targets are
refused with SENSITIVE_PATH_REFUSED unless i_accept_secret_write_risk is
true, which records a warning and is itself undoable. dry_run validates
every guard and writes nothing, returning operation_id null. Otherwise
the operation is recorded and undoable.
|
| file_writeA | Replace a whole file with new content and return operation_id and undo_available. The replacement is atomic: a crash leaves the complete previous content.
expected_hash guards against clobbering a file that changed since it was
read; a mismatch is CONTENT_CONFLICT and nothing is written. The file's
encoding and byte-order mark are inherited unless encoding is named.
Credential-shaped targets are refused unless i_accept_secret_write_risk
is true. dry_run validates and writes nothing. Otherwise the operation is
recorded and undoable. Not idempotent: each successful call adds a
history record.
|
| file_copyA | Copy one file inside the workspace and return operation_id and undo_available. An occupied destination is refused unless expected_destination_hash
matches its current content. The copy is not atomic across its two paths,
but it is recorded as one operation, so undo restores both ends. The
destination is subject to the credential-shaped refusal. dry_run writes
nothing. Otherwise the operation is undoable.
|
| file_moveA | Move or rename one file inside the workspace and return operation_id and undo_available. An occupied destination is refused unless overwrite is true, which makes
the call destructive at the destination. The move is recorded as one
operation and undo restores both ends. Credential-shaped destinations are
refused. dry_run writes nothing. Otherwise the operation is undoable.
|
| file_deleteA | Delete one file and return operation_id and undo_available. Destructive. Deletes exactly the named file: no glob, no recursion, no directory
removal, and no widening of the workspace root. expected_hash refuses the
delete when the content changed since it was read (CONTENT_CONFLICT).
dry_run validates and deletes nothing. Otherwise the operation is
recorded, and undo restores the file while nothing else has recreated
that path.
|
| directory_createA | Create one directory and return operation_id and undo_available. Additive: no existing file or directory is replaced. parents controls
whether missing ancestors may be created. dry_run validates and creates
nothing. Otherwise the operation is recorded, and undo removes the
directory only while everything inside it is exactly what the create
produced.
|
| directory_deleteA | Delete one directory and return operation_id and undo_available. Destructive. A non-empty directory requires recursive true and confirm_recursive true;
one without the other is refused before anything is touched. The scope is
exactly the named subtree inside the selected workspace root — this tool
cannot delete outside it, and Filekeeper's own .filekeeper/ state
directory is refused. dry_run lists what would be removed and deletes
nothing. Otherwise the whole tree is recorded as one operation and is
undoable.
|
| file_replace_textA | Replace literal text and return operation_id, undo_available and the match stage. Matching is staged and the result always names the stage: exact first,
then normalised (indentation and trailing whitespace tolerated, the
replacement re-based onto the matched indentation), then a NO_MATCH
refusal carrying the nearest candidate lines. match is required and is
either first or all; there is no default policy. match_count reports the
matches found, expected_match_count refuses a different number, and
expected_content pins the exact text of one region.
|
| file_replace_linesA | Replace an inclusive 1-based line range and return operation_id and undo_available. Use this for genuinely positional work; file_replace_text is cheaper when
the line numbers are not already known. Out-of-range references are
refused, never clamped. The file's newline convention and byte-order mark
are preserved, and a replacement without a trailing newline does not fuse
lines. dry_run returns a unified diff preview and writes nothing.
Otherwise the operation is recorded and undoable.
|
| file_insert_linesA | Insert text at a defined position and return operation_id and undo_available. line is a 1-based line number. position is before or after that line, or
end to append at end of file, which takes no line number; there is no
sentinel line number for end of file. Additive: no existing line is
replaced. dry_run returns a unified diff preview and writes nothing.
Otherwise the operation is recorded and undoable.
|
| file_delete_linesA | Delete an inclusive 1-based line range and return operation_id and undo_available. Out-of-range references are refused, never clamped. The file's newline
convention and byte-order mark are preserved. dry_run returns a unified
diff preview and writes nothing. Otherwise the operation is recorded and
undoable.
|
| file_apply_patchA | Apply a unified diff and return operation_id and undo_available. Destructive. The whole patch is parsed and every hunk is checked against its file
before a byte is written; a failed or ambiguous hunk rejects the patch
with PATCH_FAILED and leaves the pre-patch state intact. A patch is
limited to 1048576 bytes here. A multi-file patch is recorded as one
logical operation and is undoable, but its application is recoverable,
not atomic across files. dry_run validates and reports every file and
hunk without touching the tree. Renaming patches are refused.
|
| history_listA | List recorded operations in the selected workspace, newest first. Read-only. path narrows to operations touching that workspace-relative
path; actor and task_id are filters, not authority, and never change what
a mutation records. limit is capped at 200. Returns operation ids usable
with history_get, history_diff and undo_operation. Paths are rendered
when read: a workspace rooted at the filesystem root reports target and
item paths with their leading '/' so they are absolute.
|
| history_getA | Show one recorded operation: status, actor, paths, before/after hashes and modes. Read-only. Unknown identifiers are OPERATION_NOT_FOUND. No file content is
returned; use history_diff for a before/after diff.
|
| history_diffA | Show the recorded before/after unified diff for one operation. Read-only. Returns one entry per affected path with a textual unified
diff, or is_binary true for content that has no textual diff. Never
returns whole file bodies.
|
| undo_operationA | Undo one recorded operation and return the new operation_id and undo_available. Before writing, every affected path is compared with the operation's
recorded before and after state. A path that matches neither was changed
afterwards: the whole undo is refused with UNDO_CONFLICT and nothing is
modified. A recorded move, copy or multi-file patch is undone as one
operation. Undoing a create removes the file only while it still matches
what was created. The undo is itself recorded; a refusal is recorded as an
undo_refused row carrying the conflict code and the blocking paths, and
that row is never offered as undoable.
|
| undo_lastA | Undo the most recent undoable operation in the selected workspace. Destructive. Same conflict rules as undo_operation: any path changed after the
operation refuses the whole undo with UNDO_CONFLICT and modifies nothing.
history_skipped entries in the result were above the history size cap and
cannot be restored (HISTORY_UNAVAILABLE). The undo is itself recorded.
|
