Login
OCX: help
Login

← list

Runs create run stop attach secret daemon watchCheckout context find read edit test save wiki_read wiki_edit unversioned_list unversioned_get unversioned_putAgent's work post ticket questions card cards receipt audit unaudited sync commit_and_sync_guide commit_and_sync threadRepository hook unhook export project tag_messagesLogins approve collect register connector send_runsReleases stage accept rollback import release follow appAbout list help status echo

ocx2-cgirelease 197a37c0d8ae (green at 2026-11-06T02:32:21Z: 713 examples, 0 failures; coverage 100.0%; 2 executables build; built with no build settings)
entry point cgi login nobody capabilities ghjorz (g: clone, o: check-out) repository /var/lib/fossil/cleave.fossil dir /var/lib/fossil root /var/lib/ocx/agents-daemon remote

ocx2 — OCX's tools for work on a Fossil repository.

tools

Runs, work an actor does toward an objective: send one, start one by hand, or stop one

create

Write a version 2 run as your user from a pattern and explicit fields, addressed by to and clone: on the server, or as a reply or ticket change pushed from a clone. Admin or setup makes an absent process user when its workspace signs in. The daemon and watcher answer it later.

capabilities needed: aR (a: admin, R: send runs) ✗

output

name type required description
run string yes the run written, by its hash
where object yes where: the thread, by its first post, or the ticket
where.kind string yes ticket or forum
where.hash string yes the ticket's id, or the hash of the thread's first post, in full
made string no the user made for the run's process; absent when no account was made

run

Start a manual run on the clone's host, using its clone and project password file.

capabilities needed: s (setup) ✗

withheld: run starts a manual run on the clone's host

ocx2 run RUN [--dry-run]

run required · the run, by its hash or a prefix
dry_run optional · say what the tool would do now, changing nothing: its checks run, and its changes are only listed

output

name type required description
run string yes the run's full hash
handed list of string yes the runs handed to a watcher

stop

Ask a run's actor to end it with a stop, written where the run is, as your user on the server. An actor acts only on a stop from a user holding admin or setup, or R for a run that user sent.

capabilities needed: a (admin) ✗

output

name type required description
stop string yes the stop written, by its hash
run string yes the run, by its hash in full

attach

Join your terminal to the terminal of a run's process, at its clone's host, as the host account OCX runs as: you see what it shows and type into it, until you press Ctrl-], when you leave it running.

capabilities needed: (none)

withheld: a page holds no terminal; attach at the clone's host's command line.

ocx2 attach RUN [--dry-run]

run required · the run, by its hash or a prefix of it
dry_run optional · say what the tool would do now, changing nothing: its checks run, and its changes are only listed

output

name type required description
run string yes the run, by its hash in full
joining one of left, ended yes left, when you left, by Ctrl-] or as your terminal ended, the process going on; ended, when the process ended first

secret

Store, on the server alone, a value a run may use, such as a tunnel's key; sync never copies it. A run from a user holding admin or setup names it $$secret:NAME$$ in its process's env; the server's actor fills it in, and neither started nor kept logs show it.

capabilities needed: a (admin) ✗

output

name type required description
name string yes the secret set, by its name; its value is shown nowhere

daemon

Run this machine's clones under its service manager, pulling whole clones and handing open runs to watchers.

capabilities needed: s (setup) ✗

withheld: the daemon runs on the clone's host, under its service manager

ocx2 daemon [--dry-run]

dry_run optional · say what the tool would do now, changing nothing: its checks run, and its changes are only listed

output

name type required description
served list of object yes the clones served
served.clone string yes the clone
served.user string yes the clone user
served.server_code string yes the server-code
served.completion integer no the last completed pull's receipt number
unapproved list of string yes the entries still waiting for approval

watch

Watch one run on this acting clone and post its reports through Fossil's pages.

capabilities needed: s (setup) ✗

withheld: watch runs on the clone's host

ocx2 watch RUN SERVER CREDENTIALS [--by-hand] [--dry-run]

run required · the run's full hash
server required · the server's URL
credentials required · the actor's credentials file
by_hand optional · whether a person starts this manual run
dry_run optional · say what the tool would do now, changing nothing: its checks run, and its changes are only listed

output

name type required description
reports list of string yes the reports posted by this watcher
failure string no a failure of the watcher itself, with its backtrace for the run's log
waited boolean yes whether this run waits for a later daemon round

The checkout: read, change, test and save your work

context

Say what you are working on, first: the run's objective, if this is a run's checkout; the branch save commits on; the files changed and not saved; and the tests test may run. Then find and read files, change them with edit, run every test, and save.

capabilities needed: o (check-out) ✓

withheld: it acts on the checkout you work in, which the web page is not; call it over MCP in a run, or at a command line in a checkout

ocx2 context [--dry-run]

dry_run optional · say what the tool would do now, changing nothing: its checks run, and its changes are only listed

output

name type required description
objective string no what the run is for, and what counts as passing; absent when the checkout is not a run's
branch string yes the branch save commits your work on: never trunk
changed list of object yes each file changed and not saved
changed.path string yes the file, by its path from the checkout's root
changed.change string yes how it changed: EDITED, ADDED, DELETED and so on as Fossil says, or NEW for a file Fossil does not track yet
tests list of string yes the tests you may run, by name; save needs each to pass after your last edit

find

Find each line holding a text, exactly as written, case and all, in the checkout's files or under one path: its file, its line number and the line. Then read the file from a little before that line.

capabilities needed: o (check-out) ✓

withheld: it acts on the checkout you work in, which the web page is not; call it over MCP in a run, or at a command line in a checkout

ocx2 find TEXT [--path PATH] [--dry-run]

text required · the text to find, exactly as it is written in the file
path optional · a file or directory to search under, by its path from the checkout's root; the whole checkout when absent
dry_run optional · say what the tool would do now, changing nothing: its checks run, and its changes are only listed

output

name type required description
found list of object yes each line found, at most 50
found.path string yes the file, by its path from the checkout's root
found.line integer yes the line's number, from 1
found.text string yes the line, exactly
more integer yes how many more lines hold it than are given; 0 when all are

read

Read a file of the checkout: up to 200 lines from a line you name, exactly as they are, as text, with the numbers of its first and last lines and how many lines the file has. Copy what edit replaces from this text.

capabilities needed: o (check-out) ✓

withheld: it acts on the checkout you work in, which the web page is not; call it over MCP in a run, or at a command line in a checkout

ocx2 read PATH [--from FROM] [--dry-run]

path required · the file, by its path from the checkout's root
from optional · the number of the first line to read, from 1; 1 when absent
dry_run optional · say what the tool would do now, changing nothing: its checks run, and its changes are only listed

output

name type required description
text string yes the lines read, exactly as in the file, with no numbers added
first_line integer yes the number of the first line in text
last_line integer yes the number of the last line in text
lines integer yes how many lines the file has

edit

Change a file of the checkout: replace the text `old`, copied exactly from read's answer, with `new`. `old` must appear in the file exactly once; with `old` empty, add `new` at the file's end, making the file if there is none. It answers the changed lines as read does.

capabilities needed: i (check-in) ✗

withheld: it acts on the checkout you work in, which the web page is not; call it over MCP in a run, or at a command line in a checkout

ocx2 edit PATH OLD NEW [--dry-run]

path required · the file, by its path from the checkout's root
old required · the text now in the file that you replace, copied exactly from read's text, with no + or - marks of a diff; empty to add new at the file's end
new required · the text to put in its place, as it should read, with no + or - marks of a diff
dry_run optional · say what the tool would do now, changing nothing: its checks run, and its changes are only listed

output

name type required description
text string yes the lines read, exactly as in the file, with no numbers added
first_line integer yes the number of the first line in text
last_line integer yes the number of the last line in text
lines integer yes how many lines the file has

test

Run the project's tests in the checkout as it is now, all, or one by the name the context tool lists: whether each passed, and the last 100 lines it wrote. The save tool needs every test to pass after your last edit.

capabilities needed: i (check-in) ✗

withheld: it acts on the checkout you work in, which the web page is not; call it over MCP in a run, or at a command line in a checkout

ocx2 test [--name NAME] [--dry-run]

name optional · one test's name, exactly as context lists it; leave it out to run every test
dry_run optional · say what the tool would do now, changing nothing: its checks run, and its changes are only listed

output

name type required description
passed boolean yes true when every test run passed
tests list of object yes each test run
tests.name string yes the test's name
tests.passed boolean yes true when the test passed
tests.ended string yes how it ended: exited and its code, or stopped by its wall clock
tests.output string yes the last 100 lines it wrote to its output
tests.errors string yes the last 100 lines it wrote to its errors

save

Commit and push every change once every test has passed since your last edit: on your working branch, with a title and Intent, Expression and Demonstrates lines, as your user. It answers the check-in and who the server says sent it; with nothing changed, it pushes what is unsent.

capabilities needed: i (check-in) ✗

withheld: it acts on the checkout you work in, which the web page is not; call it over MCP in a run, or at a command line in a checkout

ocx2 save TITLE INTENT EXPRESSION DEMONSTRATES [--dry-run]

title required · what the check-in does, in one line
intent required · why it was made: what asked for it, in one line
expression required · what changed, and where, in one line
demonstrates required · the test that shows it works, in one line
dry_run optional · say what the tool would do now, changing nothing: its checks run, and its changes are only listed

output

name type required description
branch string yes the working branch it is on
checkin string no the check-in made; absent when nothing had changed
landed list of object yes the check-ins on the server, each with its link and who its receipt says sent it
landed.checkin string yes the check-in, by its hash in full
landed.link string yes where the server shows it
landed.sender string no the user the server's receipt says it came from: the run's user once it landed; absent when the server has not received it, or its receipt tool could not be asked

wiki_read

Read a wiki page as the server holds it now, by its name: its text and its version. Change it with wiki_edit.

capabilities needed: j ✓

withheld: it acts on the checkout you work in, which the web page is not; call it over MCP in a run, or at a command line in a checkout

ocx2 wiki_read NAME [--dry-run]

name required · the page's name, as Fossil's wiki names it
dry_run optional · say what the tool would do now, changing nothing: its checks run, and its changes are only listed

output

name type required description
text string yes the page's text
version string yes the version read, by its hash

wiki_edit

Change a wiki page as edit changes a file: replace `old`, copied exactly from wiki_read's answer, with `new`; `old` must appear exactly once in the page now, so no newer change is lost. With `old` empty, append `new`, making the page if none. It answers the new text and version.

capabilities needed: k ✗

withheld: it acts on the checkout you work in, which the web page is not; call it over MCP in a run, or at a command line in a checkout

ocx2 wiki_edit NAME OLD NEW [--dry-run]

name required · the page's name, as Fossil's wiki names it, not a path
old required · the text now in the page that you replace, copied exactly from wiki_read's text, with no + or - marks of a diff; empty to add new at the page's end
new required · the text to put in its place, as it should read
dry_run optional · say what the tool would do now, changing nothing: its checks run, and its changes are only listed

output

name type required description
text string yes the page's whole text now
version string yes the version written, by its hash

unversioned_list

List the unversioned files the server shares, such as binaries: each name, the hash of its content and its size.

capabilities needed: o (check-out) ✓

withheld: it acts on the checkout you work in, which the web page is not; call it over MCP in a run, or at a command line in a checkout

ocx2 unversioned_list [--dry-run]

dry_run optional · say what the tool would do now, changing nothing: its checks run, and its changes are only listed

output

name type required description
files list of object yes each unversioned file
files.name string yes the file's name
files.hash string yes the hash of its content: give it to unversioned_put as replaces, to change it
files.size integer yes its size in bytes

unversioned_get

Get an unversioned file the server shares, by its name: its content, base64, and the hash of its content.

capabilities needed: o (check-out) ✓

withheld: it acts on the checkout you work in, which the web page is not; call it over MCP in a run, or at a command line in a checkout

ocx2 unversioned_get NAME [--dry-run]

name required · the file's name, as unversioned_list gives it
dry_run optional · say what the tool would do now, changing nothing: its checks run, and its changes are only listed

output

name type required description
content string yes its content, base64
hash string yes the hash of its content

unversioned_put

Share a file, such as a binary, as an unversioned file of the server: its name and its content, base64. To change one, give the hash you last saw, so no newer one is lost. It answers the new hash.

capabilities needed: y (write-unversioned) ✗

withheld: it acts on the checkout you work in, which the web page is not; call it over MCP in a run, or at a command line in a checkout

ocx2 unversioned_put NAME CONTENT [--replaces REPLACES] [--dry-run]

name required · the file's name
content required · its content, base64
replaces optional · the hash of the version it replaces, as unversioned_list gave it; absent or empty for a new file
dry_run optional · say what the tool would do now, changing nothing: its checks run, and its changes are only listed

output

name type required description
hash string yes the hash of the content kept

An agent's work: sync check-ins, post answers, and record verdicts

post

Write a plain post as your user: a reply in the thread of the post you answer, or a change to a ticket. From your clone's checkout it is made in your clone and pushed; on the served repository, as from this page, it is made there. A reply needs Fossil's WrForum (3) or WrTForum (4), a change to a ticket its WrTkt (w) or ApndTkt (c), and Check-In (i) may make either. It refuses text that holds an OCX message, so a program's posts never carry one, and it never starts a thread or a ticket. Given for, it writes the text as a question for that user, and given run too, as the question of that run's process, yours; given decision, as your decision for the question you answer, which anyone where it is may write, and which, from its sender, or from whoever sent the run it names as asking it, confirms it answered and closes it.

capabilities needed: i34wc (i: check-in) ✗

output

name type required description
written string yes the post or ticket change written, by its hash
where object yes where: the thread, by its first post, or the ticket
where.kind string yes ticket or forum
where.hash string yes the ticket's id, or the hash of the thread's first post, in full

ticket

File a new ticket as your user on the served repository, Open, with a title and a description in Markdown; it holds no OCX message, and a run, which answers where it was asked, never files one from its clone. Needs Fossil's NewTkt (n). Refused where the server holds new tickets for a moderator and you lack ModTkt (q).

capabilities needed: n ✗

output

name type required description
ticket string yes the ticket, by its id
written string yes its first change, by its hash

questions

Say what waits on a user, as data: each question for that user that they have not decided, whoever else has; each they sent, or a run they sent asked, that has a decision, for them to confirm answered; and every other open question, oldest first. Each with its fields, where it was asked, who sent it and when, what it replies to and what it refers to described, its decisions, and who may confirm it. From a clone's checkout it asks the server who sent each question and decision. It writes nothing.

capabilities needed: 2r ✓

optional · the user whose questions they are, by login; you, when left out

output

name type required description
for string yes the user whose questions they are, by login
waiting list of object yes what waits on them: each question for them that they have not decided, whoever else has, oldest first
waiting.asked string yes the post or ticket change asking it, by its hash in full, which a decision names
waiting.where object yes the thread or ticket it is in
waiting.where.kind string yes ticket or forum
waiting.where.hash string yes the ticket's id, or the hash of the thread's first post, in full
waiting.title string yes that thread's or ticket's title, each hash in it shown by its artifact's title, or cut
waiting.link string yes where it was asked, as a link from the repository's root by the first ten digits of a hash: the post, or its ticket
waiting.url string no that link in full, from the server's public URL; absent where none is set
waiting.from string no the user the server received it from; absent when it kept none
waiting.at string yes when it was written, in UTC, as its writer's clock said
waiting.for string yes the user it asks, by login
waiting.question string yes what it asks, in words
waiting.options list of string (choice) yes its options, the one its asker recommends first; none for the user's own words
waiting.stakes string no what the decision changes; absent when not said
waiting.run string no the run whose process asks it, by its hash in full; absent when no run's process asks it
waiting.replies_to object no what it replies to, described: the post, or its ticket; absent for a thread's first post
waiting.replies_to.title string yes its title: a thread's, a ticket's, a tech-note's comment, a check-in's first comment line, a file's name and lines, or a page's name, each hash in it shown by its artifact's title, or cut to "…" when none is found; or "not readable by you", or "not in the repository"
waiting.replies_to.kind string no what it is: forum, ticket, technote, checkin, file or wiki; absent where it is not shown
waiting.replies_to.by string no the user the server received it from; for a ticket, its first change's
waiting.replies_to.at string no when it was written, in UTC, as its writer's clock said
waiting.replies_to.excerpt string no what it says: its first 300 characters, an OCX message's block left out, or the file's lines, at most 20; each hash in it shown by its artifact's title, or cut to "…" when none is found
waiting.replies_to.link string yes the link, from the repository's root
waiting.replies_to.url string no the link in full, from the repository's public URL; absent where none is set, or the link is not from the repository's root
waiting.references list of object yes what it refers to, each reference described, in its order
waiting.references.title string yes its title: a thread's, a ticket's, a tech-note's comment, a check-in's first comment line, a file's name and lines, or a page's name, each hash in it shown by its artifact's title, or cut to "…" when none is found; or "not readable by you", or "not in the repository"
waiting.references.kind string no what it is: forum, ticket, technote, checkin, file or wiki; absent where it is not shown
waiting.references.by string no the user the server received it from; for a ticket, its first change's
waiting.references.at string no when it was written, in UTC, as its writer's clock said
waiting.references.excerpt string no what it says: its first 300 characters, an OCX message's block left out, or the file's lines, at most 20; each hash in it shown by its artifact's title, or cut to "…" when none is found
waiting.references.link string yes the link, from the repository's root
waiting.references.url string no the link in full, from the repository's public URL; absent where none is set, or the link is not from the repository's root
waiting.decisions list of object yes each decision that counts, oldest first
waiting.decisions.from string no the user the server received it from; absent when it kept none
waiting.decisions.at string yes when it was written, in UTC, as its writer's clock said
waiting.decisions.note string yes its note: its writer's words, or the words of the option chosen, each hash in it shown by its artifact's title, or cut to "…" when none is found
waiting.confirmers list of string yes who may confirm it answered, by login: its sender, and who sent the run it names as asking it, when that run counts; none when the server kept no sender for it
to_confirm list of object yes each question they sent, or a run they sent asked, that has a decision, for them to confirm answered, oldest first
to_confirm.asked string yes the post or ticket change asking it, by its hash in full, which a decision names
to_confirm.where object yes the thread or ticket it is in
to_confirm.where.kind string yes ticket or forum
to_confirm.where.hash string yes the ticket's id, or the hash of the thread's first post, in full
to_confirm.title string yes that thread's or ticket's title, each hash in it shown by its artifact's title, or cut
to_confirm.link string yes where it was asked, as a link from the repository's root by the first ten digits of a hash: the post, or its ticket
to_confirm.url string no that link in full, from the server's public URL; absent where none is set
to_confirm.from string no the user the server received it from; absent when it kept none
to_confirm.at string yes when it was written, in UTC, as its writer's clock said
to_confirm.for string yes the user it asks, by login
to_confirm.question string yes what it asks, in words
to_confirm.options list of string (choice) yes its options, the one its asker recommends first; none for the user's own words
to_confirm.stakes string no what the decision changes; absent when not said
to_confirm.run string no the run whose process asks it, by its hash in full; absent when no run's process asks it
to_confirm.replies_to object no what it replies to, described: the post, or its ticket; absent for a thread's first post
to_confirm.replies_to.title string yes its title: a thread's, a ticket's, a tech-note's comment, a check-in's first comment line, a file's name and lines, or a page's name, each hash in it shown by its artifact's title, or cut to "…" when none is found; or "not readable by you", or "not in the repository"
to_confirm.replies_to.kind string no what it is: forum, ticket, technote, checkin, file or wiki; absent where it is not shown
to_confirm.replies_to.by string no the user the server received it from; for a ticket, its first change's
to_confirm.replies_to.at string no when it was written, in UTC, as its writer's clock said
to_confirm.replies_to.excerpt string no what it says: its first 300 characters, an OCX message's block left out, or the file's lines, at most 20; each hash in it shown by its artifact's title, or cut to "…" when none is found
to_confirm.replies_to.link string yes the link, from the repository's root
to_confirm.replies_to.url string no the link in full, from the repository's public URL; absent where none is set, or the link is not from the repository's root
to_confirm.references list of object yes what it refers to, each reference described, in its order
to_confirm.references.title string yes its title: a thread's, a ticket's, a tech-note's comment, a check-in's first comment line, a file's name and lines, or a page's name, each hash in it shown by its artifact's title, or cut to "…" when none is found; or "not readable by you", or "not in the repository"
to_confirm.references.kind string no what it is: forum, ticket, technote, checkin, file or wiki; absent where it is not shown
to_confirm.references.by string no the user the server received it from; for a ticket, its first change's
to_confirm.references.at string no when it was written, in UTC, as its writer's clock said
to_confirm.references.excerpt string no what it says: its first 300 characters, an OCX message's block left out, or the file's lines, at most 20; each hash in it shown by its artifact's title, or cut to "…" when none is found
to_confirm.references.link string yes the link, from the repository's root
to_confirm.references.url string no the link in full, from the repository's public URL; absent where none is set, or the link is not from the repository's root
to_confirm.decisions list of object yes each decision that counts, oldest first
to_confirm.decisions.from string no the user the server received it from; absent when it kept none
to_confirm.decisions.at string yes when it was written, in UTC, as its writer's clock said
to_confirm.decisions.note string yes its note: its writer's words, or the words of the option chosen, each hash in it shown by its artifact's title, or cut to "…" when none is found
to_confirm.confirmers list of string yes who may confirm it answered, by login: its sender, and who sent the run it names as asking it, when that run counts; none when the server kept no sender for it
open list of object yes every other question still open, their own that no one has decided among them, oldest first
open.asked string yes the post or ticket change asking it, by its hash in full, which a decision names
open.where object yes the thread or ticket it is in
open.where.kind string yes ticket or forum
open.where.hash string yes the ticket's id, or the hash of the thread's first post, in full
open.title string yes that thread's or ticket's title, each hash in it shown by its artifact's title, or cut
open.link string yes where it was asked, as a link from the repository's root by the first ten digits of a hash: the post, or its ticket
open.url string no that link in full, from the server's public URL; absent where none is set
open.from string no the user the server received it from; absent when it kept none
open.at string yes when it was written, in UTC, as its writer's clock said
open.for string yes the user it asks, by login
open.question string yes what it asks, in words
open.options list of string (choice) yes its options, the one its asker recommends first; none for the user's own words
open.stakes string no what the decision changes; absent when not said
open.run string no the run whose process asks it, by its hash in full; absent when no run's process asks it
open.replies_to object no what it replies to, described: the post, or its ticket; absent for a thread's first post
open.replies_to.title string yes its title: a thread's, a ticket's, a tech-note's comment, a check-in's first comment line, a file's name and lines, or a page's name, each hash in it shown by its artifact's title, or cut to "…" when none is found; or "not readable by you", or "not in the repository"
open.replies_to.kind string no what it is: forum, ticket, technote, checkin, file or wiki; absent where it is not shown
open.replies_to.by string no the user the server received it from; for a ticket, its first change's
open.replies_to.at string no when it was written, in UTC, as its writer's clock said
open.replies_to.excerpt string no what it says: its first 300 characters, an OCX message's block left out, or the file's lines, at most 20; each hash in it shown by its artifact's title, or cut to "…" when none is found
open.replies_to.link string yes the link, from the repository's root
open.replies_to.url string no the link in full, from the repository's public URL; absent where none is set, or the link is not from the repository's root
open.references list of object yes what it refers to, each reference described, in its order
open.references.title string yes its title: a thread's, a ticket's, a tech-note's comment, a check-in's first comment line, a file's name and lines, or a page's name, each hash in it shown by its artifact's title, or cut to "…" when none is found; or "not readable by you", or "not in the repository"
open.references.kind string no what it is: forum, ticket, technote, checkin, file or wiki; absent where it is not shown
open.references.by string no the user the server received it from; for a ticket, its first change's
open.references.at string no when it was written, in UTC, as its writer's clock said
open.references.excerpt string no what it says: its first 300 characters, an OCX message's block left out, or the file's lines, at most 20; each hash in it shown by its artifact's title, or cut to "…" when none is found
open.references.link string yes the link, from the repository's root
open.references.url string no the link in full, from the repository's public URL; absent where none is set, or the link is not from the repository's root
open.decisions list of object yes each decision that counts, oldest first
open.decisions.from string no the user the server received it from; absent when it kept none
open.decisions.at string yes when it was written, in UTC, as its writer's clock said
open.decisions.note string yes its note: its writer's words, or the words of the option chosen, each hash in it shown by its artifact's title, or cut to "…" when none is found
open.confirmers list of string yes who may confirm it answered, by login: its sender, and who sent the run it names as asking it, when that run counts; none when the server kept no sender for it

card

Answer a project's card/NAME wiki definition across the named repositories, as data. Reads only.

capabilities needed: o (check-out) ✓

required · the project defining the card
required · the card name after card/
required · repository files, separated by newlines when more than one; on the web page only the one it serves; the current repository when blank
optional · login for $viewer; the caller by default
optional · current time, RFC 3339; the clock by default

output

name type required description
project string yes the repository project defining the card
name string yes the card's wiki name after card/
title string yes the card's title
as_of string no the newest check-in, forum post or ticket event in any named repository, UTC
count integer yes the number of items found before the limit
say string yes the rendered sentence
items list of table of string yes each selected item, with its project

cards

Answer every card/NAME wiki definition in the named repositories. Reads only.

capabilities needed: o (check-out) ✓

required · repository files, separated by newlines when more than one; on the web page only the one it serves; the current repository when blank
optional · login for $viewer; the caller by default
optional · current time, RFC 3339; the clock by default

output

name type required description
as_of string no the newest check-in, forum post or ticket event in any named repository, UTC
cards list of object yes each card's project, name, title, count and sentence
cards.project string yes the repository project defining the card
cards.name string yes the card's wiki name after card/
cards.title string yes the card's title
cards.count integer yes the number of items found before the limit
cards.say string yes the rendered sentence

receipt

Say who sent each artifact: the user the server received it from, what that user may do there, and the order in which the server received it, or that it has not; or what one user may do, and whether the wiki edits they save, and the ticket changes they make in its ticket pages, wait for a moderator. Never an IP address. From a clone it asks the server.

capabilities needed: (none)

optional · the artifacts, by their hashes in full, separated by spaces
optional · a user whose capabilities, and whether a moderator holds their wiki edits and ticket changes, to report

output

name type required description
artifacts list of object yes each artifact asked of, in the order asked
artifacts.artifact string yes the artifact, by its hash in full
artifacts.received boolean yes whether the server has received it; false too for one you may not read
artifacts.sender string no the user the server received it from; absent when it has not received it, or kept no user for it
artifacts.capabilities string (fossil-capabilities) no what that user may do on the server, as Fossil grants it, inherited capabilities included
artifacts.receipt integer no the number of the server's receipt, which orders what it received
artifacts.rid integer no the artifact's row number on the server, which orders the artifacts of one receipt
user object no the user asked of; absent when none was
user.user string yes the user
user.capabilities string (fossil-capabilities) no what the user may do on the server, as Fossil grants it; absent when the server has no such user, or you may not read
user.wiki_moderated boolean no whether the server holds each wiki edit the user saves for a moderator: it moderates wiki edits, and the user lacks ModWiki (l); absent as capabilities is
user.ticket_moderated boolean no whether the server holds each ticket change the user makes in its ticket pages for a moderator: it moderates ticket changes, and the user lacks ModTkt (q); absent as capabilities is
asked string no the server asked, from a clone, by its URL: it answers as to anyone, so what anyone may not read reads as not received; absent on the served repository

audit

Record a verdict on a check-in: tag it audited with pass or fail, a note, and the objective it was judged against, as your user (docs/protocol-v2-verdicts.md). No one may audit their own check-in. From a clone, the tag is pushed; either way, the verdict is then read back from the served repository, so a verdict Fossil did not keep is never reported as given.

capabilities needed: i (check-in) ✗

output

name type required description
checkin string yes the check-in, in full
tag string yes the tag's artifact
held string yes the verdict as the served repository holds it: pass or fail, a colon, the note, and (against X)
by string no the user Fossil received the verdict from

unaudited

List the check-ins that change files and that no verdict that counts has judged (docs/protocol-v2-verdicts.md): on one branch or every branch, oldest first in the order the server received them, at most 50, with how many there are. From a clone's checkout it asks the server. It writes nothing.

capabilities needed: (none)

optional · the branch whose check-ins are listed; every branch when absent

output

name type required description
checkins list of object yes the check-ins no verdict that counts has judged, oldest first, at most 50
checkins.checkin string yes the check-in, by its hash in full
checkins.branch string no its branch, as Fossil's timeline shows it
checkins.user string no the user it names, as its writer gave it
checkins.comment string no its comment, as the timeline shows it
count integer yes how many there are, those not given included
asked string no the server asked, from a clone, by its URL; absent on the served repository

sync

For an agent outside every run's checkout that keeps no Fossil password: push your clone's check-ins by giving a base64 bundle of your working branch, each comment with Intent, Expression and Demonstrates lines; checked, they are pushed as the user of the run whose process answers this call. Give have, a check-in you hold, for later ones. In a run's checkout, on any host? Your commits push as you make them; if one did not, run `fossil push`.

capabilities needed: i (check-in) ✗

output

name type required description
pushed list of string yes the check-ins pushed to the server, by their hashes as the bundle lists them
landed list of object yes each check-in pushed, as the server holds it: its hash in full, its link, and who the server's receipt says sent it
landed.checkin string yes the check-in, by its hash in full
landed.link string yes where the server shows it
landed.sender string no the user the server's receipt says it came from: the run's user once it landed; absent when the server has not received it, or its receipt tool could not be asked
bundle string no every check-in after the one you hold, as a bundle, base64; absent without have, or when none follows it
apply string no how to apply the bundle in your clone

commit_and_sync_guide

For an agent outside every run's checkout that keeps no Fossil password: say, as shell commands, how to commit your own clone's work and get it to the server: check you are on your working branch, commit with the comment this writes from what you give, bundle the branch, and give it to sync. In a run's checkout, on any host? Your commits push as you make them; if one did not, run `fossil push`.

capabilities needed: (none)

required · your working branch, never trunk
optional · what the check-in does, in a line
optional · why: what asked for it
optional · what changed, and where
optional · the spec file or command that shows it works

output

name type required description
message string yes the check-in's comment, filled from what you gave
steps list of string yes the steps, each a command for your own shell or a call to make

commit_and_sync

For an agent outside every run's checkout that keeps no Fossil password, from ocx2 --mcp on its own machine: commit every change in your own clone once every test has passed since your last edit, new files included, on your working branch, with a title and Intent, Expression and Demonstrates lines; answer the branch's bundle for sync. Elsewhere it points to commit_and_sync_guide. In a run's checkout, on any host? Your commits push as you make them; if one did not, run `fossil push`.

capabilities needed: i (check-in) ✗

withheld: it acts on your own checkout, which the web page is not where; see commit_and_sync_guide

ocx2 commit_and_sync BRANCH TITLE INTENT EXPRESSION DEMONSTRATES [--dry-run]

branch required · your working branch, never trunk
title required · what the check-in does, in a line
intent required · why: what asked for it
expression required · what changed, and where
demonstrates required · the spec file or command that shows it works
dry_run optional · say what the tool would do now, changing nothing: its checks run, and its changes are only listed

output

name type required description
committed string yes the check-in made, by its hash
bundle string yes the branch, as a bundle, base64, for ocx_sync's bundle
next_call string yes the call to make next

thread

Read a thread or a ticket, named by the hash, or a prefix of it, of any of its posts or changes, such as your run's: each post or change, oldest first in the order the server received them, with who sent it, when and its text; at most 20, after the one you give. From your clone's checkout it pulls first. It writes nothing.

capabilities needed: o (check-out) ✓

withheld: Fossil's own forum and ticket pages show a thread and a ticket's changes; read them there.

ocx2 thread OF [--after AFTER] [--dry-run]

of required · the thread or ticket: the hash, or a prefix of it, of any of its posts or changes, or the ticket's id
after optional · a post or change of it the server has received, by its hash or a prefix of it: only what follows it is read; from the first when absent
dry_run optional · say what the tool would do now, changing nothing: its checks run, and its changes are only listed

output

name type required description
where object yes where: the thread, by its first post, or the ticket
where.kind string yes ticket or forum
where.hash string yes the ticket's id, or the hash of the thread's first post, in full
conversation string no the name a person gave the thread with ocx-console's menu, as it is now; absent when it has none, and for a ticket
posts list of object yes each post or change, oldest first, at most 20
posts.hash string yes the post or change, by its hash in full; give it as after to read what follows it
posts.from string no who sent it: the user the server received it from; absent for one received from no user it keeps, and for one the server has not received, a write in your clone not pushed yet, which comes last
posts.when string yes when it was written, in UTC, as its writer's clock said
posts.text string yes its text, in Markdown, an OCX message's block included
more integer yes how many more follow than are given; 0 when all are, else read on with after the last hash given

The repository and its actor

hook

Install Fossil's own git export as the after-receive hook, replacing any old ocx2-hook command.

capabilities needed: s (setup) ✗

What hook would do now

Worked out when this page loaded: the checks ran; the changes have not been made.

  1. check read_hook read Fossil's export hook, other after-receive programs, backoffice settings and the timeline chat user · repository /var/lib/fossil/cleave.fossil

stops nobody lacks what hook needs: any of the Fossil capabilities s (setup); it holds ghjorz (g: clone, o: check-out)

output

name type required description
outcome one of installed, replaced, unchanged yes installed; replaced, when a hook run with another command, or more than once, was deleted first; or unchanged, when the repository already ran it as this root installs it
hook object yes where the hook stands now, read back
hook.state one of installed, other, absent yes installed once as Fossil's export; other when an old or repeated hook remains; absent otherwise
hook.command string no the installed command, when present
hook.others list of string yes the other after-receive programs
hook.backoffice one of queued, nodelay, disabled yes when Fossil runs its backoffice
hook.chat_user string no the chat user naming timeline events, when configured

unhook

Remove Fossil's export hook and any old ocx2-hook command, leaving every other hook.

capabilities needed: s (setup) ✗

What unhook would do now

Worked out when this page loaded: the checks ran; the changes have not been made.

  1. check read_hook read Fossil's export hook, other after-receive programs, backoffice settings and the timeline chat user · repository /var/lib/fossil/cleave.fossil
  2. change delete_hooks delete Fossil's export command and any old ocx2-hook command, leaving other hooks · repository /var/lib/fossil/cleave.fossil

stops nobody lacks what unhook needs: any of the Fossil capabilities s (setup); it holds ghjorz (g: clone, o: check-out)

output

name type required description
outcome one of removed, absent yes removed; or absent, when the repository did not run it
hook object yes where the hook stands now, read back
hook.state one of installed, other, absent yes installed once as Fossil's export; other when an old or repeated hook remains; absent otherwise
hook.command string no the installed command, when present
hook.others list of string yes the other after-receive programs
hook.backoffice one of queued, nodelay, disabled yes when Fossil runs its backoffice
hook.chat_user string no the chat user naming timeline events, when configured

export

Bring the server's git export, the git repository Fossil writes from it, up to date. One export runs at a time: asking during one makes it run once more after. OCX's hook does this whenever a check-in arrives. A dry run only says where the export stands.

capabilities needed: s (setup) ✗

What export would do now

Worked out when this page loaded: the checks ran; the changes have not been made.

  1. check find_export find the repository's git export where its last-git-export-repo setting says, and read where it stands, as fossil git status says, with OCX's last run of it · repository /var/lib/fossil/cleave.fossil
  2. change export_to_git export the check-ins waiting, with fossil git export, one run at a time: while another run holds the export, ask it to export again instead; it exports until no run asks · mirror /var/lib/ollama-codex/git-mirror/cleave · awaiting 0 · autopush off

stops nobody lacks what export needs: any of the Fossil capabilities s (setup); it holds ghjorz (g: clone, o: check-out)

output

name type required description
ran object no this export's run; absent when another run held the export and was asked to export again
ran.when string yes when it began, in UTC
ran.took_ms number yes how long it took, in milliseconds, with the exports it made again
ran.runs integer yes how many times it exported: once, and again for each run asked for while it did
ran.added list of integer no the check-ins Fossil said it added, by export; absent when an export failed
ran.failure string no why it failed, as Fossil said; absent when it did not
state object yes where the export stands after it
state.mirror string yes the export's directory
state.awaiting integer no how many check-ins wait to be exported; absent when Fossil cannot say
state.unreadable string no why Fossil cannot say where the export stands, as when an export was killed before Fossil kept anything; the next export mends it
state.last_export string no when Fossil last exported, as it says; absent before its first
state.autopush string no where Fossil pushes after each export, or off; set only by `fossil git export --autopush`
state.main_branch string no the git branch Fossil's trunk is exported as
state.last object no OCX's last run of it; absent before its first
state.last.when string yes when it began, in UTC
state.last.took_ms number yes how long it took, in milliseconds, with the exports it made again
state.last.runs integer yes how many times it exported: once, and again for each run asked for while it did
state.last.added list of integer no the check-ins Fossil said it added, by export; absent when an export failed
state.last.failure string no why it failed, as Fossil said; absent when it did not

project

Make a served repository, empty or from git, with its export, hook, ticket fields, clone and process users ready. The running daemon makes its clone within a minute. The web page runs it detached.

capabilities needed: s (setup) ✗

output

name type required description
repository string yes the new repository
mirror string yes its git export
checkins integer no how many check-ins it starts with, each the upstream's own commit in its export; absent while it goes on detached
main_branch string no the git branch its trunk exports as, the upstream's own; absent while it goes on detached
hook string no the hook's command on it; absent when this release's hook is not installed on the served repository
url string no its public URL, set as its email-url, which a run's clone is made from (HISTORY.md decision 25): the served repository's with its name; absent when that has none, and then its administrator sets it
login_group string no the login group it shares with the served repository, so signing in to either signs in to the other, for a user both have: the caller, its admin; absent while it goes on detached
detached object no from the web page, the import going on, detached, so the page answers at once: its process, and where it writes its outcome once it ends, which status shows; absent at the command line, which answers once it ends
detached.pid integer yes the process importing, by its number on this host, which status lists while it runs
detached.log string yes the import log, in which it writes its outcome as one line once it ends, which status shows
detached.output string yes its own output: its answer as JSON, each operation it did, once it ends
next string yes the one step to make the daemon's clone

tag_messages

Tag every OCX message the repository holds that lacks its ocx-message tag, or carries a wrong value, in one control artifact, as your user, as the actor's check does: on the served repository, or from your clone's checkout, pulled first and pushed after. It needs Fossil's Check-In (i), answers what it tagged, by kind, and decides nothing about any run.

capabilities needed: i (check-in) ✗

What tag_messages would do now

Worked out when this page loaded: the checks ran; the changes have not been made.

  1. change tag_untagged read every post and ticket change holding an OCX message, as the actor's check reads them, and tag each that lacks the ocx-message tag, or carries another value, in one control artifact, as the caller: on the served repository, or in the caller's clone and pushed · user nobody

stops nobody lacks what tag_messages needs: any of the Fossil capabilities i (check-in); it holds ghjorz (g: clone, o: check-out)

output

name type required description
tagged list of object yes each kind of message tagged, with the artifacts tagged as holding one, by kind; empty when every message carried its tag
tagged.kind string yes the messages' kind, as the first word of their tag's value says: run, stop, started, ended or another the protocol names
tagged.artifacts list of string yes each artifact tagged as holding one, by its hash in full

Logins: ask for one, approve it, collect its password, or let one send runs

approve

Approve a login someone asked for, with one press: open only a link the asker printed itself. It makes that user holding exactly the capabilities the link asks, never admin or setup, with a password no page shows, which the asker may collect with its code.

capabilities needed: a (admin) ✗

output

name type required description
login string yes the login approved
capabilities string (fossil-capabilities) yes the capabilities it holds

collect

Give the asker of an approved login its password, for the code whose SHA-256 its link gave, which only the asker holds; or, without a code, to a signed-in login the password is approved for. Register sends the code in a POST's body, never in a URL. It needs no capability and changes nothing.

capabilities needed: (none)

required · the login asked for
optional · the code the asker made, whose SHA-256 its link gave; absent, only a signed-in login the password is approved for may collect

output

name type required description
login string yes the login
password string yes its password

register

Ask the server for a login, from your own machine: the first call makes a code, keeps it in your file of passwords and prints a link for an admin to approve; once approved, a call collects the password into the file in place of the code.

capabilities needed: (none)

withheld: register is called on the asker's own machine, which keeps its file of passwords, from its command line.

ocx2 register SERVER CREDENTIALS [--login LOGIN] [--capabilities CAPABILITIES] [--dry-run]

server required · the server's URL: https, or http on this host alone
credentials required · the file of passwords, readable by its owner alone: register makes it, holding the login and its code until an admin approves the login, then its password in place of the code
login optional · the login to ask for, when there is no file of passwords yet: lowercase letters, digits and dashes
capabilities optional · the Fossil capability letters to ask for, never a or s, when there is no file of passwords yet: by default goC4w, clone, check-out, chat and unmoderated forum and ticket writing; later, those the file keeps, or none
dry_run optional · say what the tool would do now, changing nothing: its checks run, and its changes are only listed

output

name type required description
login string yes the login
password one of collected, held yes collected, when this call collected the password and kept it in place of the code; or held, when the file held it already

connector

Make the key a connector, such as claude.ai's, reaches this repository's MCP with, acting as one login once a login holding setup approves it through OAuth, and show its URL once; or revoke it. A login holding admin or setup is refused. Each call acts with the login's capabilities as Fossil holds them then, and lists only status, questions, thread, post, ticket.

capabilities needed: s (setup) ✗

output

name type required description
login string yes the login the key acts as
url string no the URL to give the connector, shown this once, holding the key; absent when revoked

send_runs

Let a user of the served repository send runs, and stop the runs it sent: add R to the letters it holds, or with off take R away, in one write that leaves every other letter as it is, and say what it may do then. An actor takes a run from a user holding R alone within the run isolation rules.

capabilities needed: a (admin) ✗

output

name type required description
user string yes the user
capabilities string (fossil-capabilities) yes what the user may do on the served repository now, as Fossil grants it, inherited capabilities included, as receipt reads it
note string no what R does not say of this user: that it holds admin or setup, which send any run with or without R; or, R taken away, that Fossil's own users lend it R still; absent otherwise

Releases: stage, accept or roll back

stage

Check, build and stage a release: run a committed Fossil checkout's own checks (crystal run ci.cr), build its programs (shards build), copy them into the release root's staged/, named by the check-in's first twelve hex digits, smoke each, and offer the release as next. Nothing served changes until accept.

capabilities needed: s (setup) ✗

withheld: it runs the checkout's own code as the web server's account; run it from the command line or MCP.

ocx2 stage CHECKOUT [--root ROOT] [--dry-run]

checkout required · a Fossil checkout with every change committed, as a directory; a relative one starts where you run the tool
root optional · the release root; by default, the root this program was released into, which the web page always uses
dry_run optional · say what the tool would do now, changing nothing: its checks run, and its changes are only listed

output

name type required description
release string yes the release's name: the first twelve hex digits of its check-in
programs list of string yes the programs released
gate string yes the gate's note: when it was green, the spec summary and the build settings
releases object yes what the release root serves and offers now
releases.current string (check-in) no the release served, the active release candidate, which ocx2-cgi runs; absent if none
releases.previous string (check-in) no the release served before it, which rollback serves again; absent if none
releases.next string (check-in) no the release offered as next, the pre-release candidate, which ocx2-cgi-next runs; absent if none
releases.changes string (changes) no what the tool changed, from the release it replaced to current, after accept, rollback or follow; else what next changes from current, while another release is offered; absent unless both are named

accept

Serve the pre-release candidate (staged/next in the release root) as the active release candidate (current); what was served becomes previous. Only a user holding setup may; called as the pre-release candidate's page, ocx2-cgi-next, it accepts only a first release, while none is served.

capabilities needed: s (setup) ✗

What accept would do now

Worked out when this page loaded: the checks ran; the changes have not been made.

  1. check find_offered find the release the staged area offers as next, unless it is already served · root /var/lib/ocx/agents-daemon

stops nobody lacks what accept needs: any of the Fossil capabilities s (setup); it holds ghjorz (g: clone, o: check-out); next is 197a37c0d8ae, which is served already

output

name type required description
current string (check-in) no the release served, the active release candidate, which ocx2-cgi runs; absent if none
previous string (check-in) no the release served before it, which rollback serves again; absent if none
next string (check-in) no the release offered as next, the pre-release candidate, which ocx2-cgi-next runs; absent if none
changes string (changes) no what the tool changed, from the release it replaced to current, after accept, rollback or follow; else what next changes from current, while another release is offered; absent unless both are named

rollback

Serve the previous release again as the active release candidate; a second rollback undoes the first. Both pages, ocx2-cgi and ocx2-cgi-next, roll back.

capabilities needed: s (setup) ✗

What rollback would do now

Worked out when this page loaded: the checks ran; the changes have not been made.

  1. check find_previous find the release the root served before the current one · root /var/lib/ocx/agents-daemon
  2. change roll_back serve the previous release again, which ocx2-cgi then runs, keeping the release it replaces as previous · root /var/lib/ocx/agents-daemon · name 0397ade7223b · replaces 197a37c0d8ae

stops nobody lacks what rollback needs: any of the Fossil capabilities s (setup); it holds ghjorz (g: clone, o: check-out)

output

name type required description
current string (check-in) no the release served, the active release candidate, which ocx2-cgi runs; absent if none
previous string (check-in) no the release served before it, which rollback serves again; absent if none
next string (check-in) no the release offered as next, the pre-release candidate, which ocx2-cgi-next runs; absent if none
changes string (changes) no what the tool changed, from the release it replaced to current, after accept, rollback or follow; else what next changes from current, while another release is offered; absent unless both are named

import

Count a builder's stage run by the server's receipts, check its files, copy and smoke it, and offer it as next; remove the shared files.

capabilities needed: s (setup) ✗

output

name type required description
current string (check-in) no the release served, the active release candidate, which ocx2-cgi runs; absent if none
previous string (check-in) no the release served before it, which rollback serves again; absent if none
next string (check-in) no the release offered as next, the pre-release candidate, which ocx2-cgi-next runs; absent if none
changes string (changes) no what the tool changed, from the release it replaced to current, after accept, rollback or follow; else what next changes from current, while another release is offered; absent unless both are named

release

Read current and previous, their names and SHA-256 inventories; read a listed file of either release, base64. Only a signed-in setup login or a listed builder may read.

capabilities needed: (none)

root /var/lib/ocx/agents-daemon set by the server · the release root; by default, the root this program was released into, which the web page always uses
optional · the name of current or previous, with --file; absent to list both releases
optional · one file listed in that release's release.txt, with --release

output

name type required description
current object no current's name and files; null when none
current.name string yes the release name, its check-in's recorded abbreviation
current.files table of string yes every file in release.txt, by name with its SHA-256 from that inventory
previous object no previous's name and files; null when none
previous.name string yes the release name, its check-in's recorded abbreviation
previous.files table of string yes every file in release.txt, by name with its SHA-256 from that inventory
content string no the requested file's exact bytes, base64; absent when listing releases

follow

Run the server's accepted current release on this client, keeping the release it leaves as previous. Start the daemon again with confine daemon after current moves.

capabilities needed: (none)

withheld: follow runs inside the client's root, as its owner, from the command line

ocx2 follow SERVER [--root ROOT] [--dry-run]

server required · the served repository's URL
root optional · the release root; by default, the root this program was released into, which the web page always uses
dry_run optional · say what the tool would do now, changing nothing: its checks run, and its changes are only listed

output

name type required description
releases object yes the client's release links
releases.current string (check-in) no the release served, the active release candidate, which ocx2-cgi runs; absent if none
releases.previous string (check-in) no the release served before it, which rollback serves again; absent if none
releases.next string (check-in) no the release offered as next, the pre-release candidate, which ocx2-cgi-next runs; absent if none
releases.changes string (changes) no what the tool changed, from the release it replaced to current, after accept, rollback or follow; else what next changes from current, while another release is offered; absent unless both are named
note string yes whether current moved, or was already the server's current

app

Name the stage pattern and the builder whose runs may be imported as releases of this repository's program APP, which the page then serves at ext/ocx2-cgi/app/APP once one is accepted; import, accept and rollback given --app release it as they release OCX. The builder gets y (write unversioned) on this repository, to send its runs' files. Only a user holding setup may.

capabilities needed: s (setup) ✗

output

name type required description
root string yes the app's release root

About this program

list

List every tool: what it does, who may run it, whether this entry point offers it, and the shape of its input; and, for a tool that changes something and needs no input, what a dry run of it says now. This list is what runs when no tool is named, and what MCP's tools/list gives.

capabilities needed: (none)

output

name type required description
program string yes the program
about string yes what it is
tools list of object yes every tool: what it does, who may run it, and the shape of a call to it
tools.name string yes the tool's name
tools.summary string yes what it does
tools.group string yes the group it is listed in
tools.capabilities_needed string (fossil-capabilities) yes the Fossil capabilities, any one of which lets a user run it; none when anyone may
tools.withheld string no why this entry point does not offer it; absent when it does
tools.defined_in string yes where it is defined: its source file, from the checkout's root, and the line that declares it
tools.input object yes the shape of its input: what a call gives it
tools.output object no the shape of its output, an answer's result (help)
tools.dry_run_now object no what a dry run of it with no input says now, for a tool that changes something and needs no input
tools.dry_run_now.log list of object yes the operations it would perform, in order: its checks performed, its changes only listed
tools.dry_run_now.stopped string no why the tool would stop now; absent when it would run to the end
context object no the shape of the context every tool receives, which the entry point resolves (help)
answer object no the shape of every answer, whose result is the tool's output (help)
releases list of object no where releases live, under ROOT: a release tool's root, or else the root this program was released into (help)
releases.path string yes the place, under the release root ROOT
releases.holds string yes what it holds

help

Give what the list tool gives, with more detail: the shape of each tool's output, of the context every tool receives and of every answer, and where releases live.

capabilities needed: (none)

output

name type required description
program string yes the program
about string yes what it is
tools list of object yes every tool: what it does, who may run it, and the shape of a call to it
tools.name string yes the tool's name
tools.summary string yes what it does
tools.group string yes the group it is listed in
tools.capabilities_needed string (fossil-capabilities) yes the Fossil capabilities, any one of which lets a user run it; none when anyone may
tools.withheld string no why this entry point does not offer it; absent when it does
tools.defined_in string yes where it is defined: its source file, from the checkout's root, and the line that declares it
tools.input object yes the shape of its input: what a call gives it
tools.output object no the shape of its output, an answer's result (help)
tools.dry_run_now object no what a dry run of it with no input says now, for a tool that changes something and needs no input
tools.dry_run_now.log list of object yes the operations it would perform, in order: its checks performed, its changes only listed
tools.dry_run_now.stopped string no why the tool would stop now; absent when it would run to the end
context object no the shape of the context every tool receives, which the entry point resolves (help)
answer object no the shape of every answer, whose result is the tool's output (help)
releases list of object no where releases live, under ROOT: a release tool's root, or else the root this program was released into (help)
releases.path string yes the place, under the release root ROOT
releases.holds string yes what it holds

status

Show the caller, release and export hook, record runs for every clone user named by an administrator, and the daemon's last round. With --login and a clone, include the actor's offer, local care and processes.

capabilities needed: (none)

output

name type required description
release string no the release this program runs from, with its gate note; absent outside a release
context object yes who called and from where, as the entry point resolved it
context.entry_point one of cli, cgi, mcp, git yes how the program was entered: cli, cgi or mcp, the entry points to the tools; or git, serving a repository's git export to git clients, neither of which reaches a tool
context.preview boolean yes whether this program is the pre-release candidate, run from the release offered as next
context.login string no the user acting; absent when none is known
context.capabilities string (fossil-capabilities) yes the user's Fossil capabilities; none when no repository says
context.repository string no the repository acted on; absent when there is none
context.checkout string no the checkout the caller is in; absent outside one
context.dir string yes the directory the caller runs in, where relative names start
context.root string no the release root this program was released into; absent when it was not
context.sources table of string yes where each setting came from
context.request list of string yes the names of the request fields the web page read
context.environment list of string yes the names, never the values, of the environment variables present but not read
context.remote boolean no whether the caller reaches this program from elsewhere: the web page, or MCP over HTTP or a tunnel; a tool that acts on the caller's own files works only where it is not
releases object no what the release root serves and offers; absent when this program was not released into one
releases.current string (check-in) no the release served, the active release candidate, which ocx2-cgi runs; absent if none
releases.previous string (check-in) no the release served before it, which rollback serves again; absent if none
releases.next string (check-in) no the release offered as next, the pre-release candidate, which ocx2-cgi-next runs; absent if none
releases.changes string (changes) no what the tool changed, from the release it replaced to current, after accept, rollback or follow; else what next changes from current, while another release is offered; absent unless both are named
hook object no where the export hook stands; absent when no readable repository is named
hook.state one of installed, other, absent yes installed once as Fossil's export; other when an old or repeated hook remains; absent otherwise
hook.command string no the installed command, when present
hook.others list of string yes the other after-receive programs
hook.backoffice one of queued, nodelay, disabled yes when Fossil runs its backoffice
hook.chat_user string no the chat user naming timeline events, when configured
offer object no the actor's offer: its user, clone server-code and enforced limits; absent on the served repository
offer.login string yes the clone user that answers runs on this clone
offer.server_code string no this clone's server-code, named by a run's clone field
offer.limits list of string yes the limits this actor enforces
runs list of object no each readable open run for the clone users the record names; with --login, the actor and its local care
runs.run string yes the run, by its hash in full
runs.where object yes the thread or ticket it is in, where its reports are written
runs.where.kind string yes ticket or forum
runs.where.hash string yes the ticket's id, or the hash of the thread's first post, in full
runs.objective string no its objective; absent for a run that does not read
runs.user string no its process's user; absent for a run that does not read
runs.project string no the project of the repository it is in; absent for the served repository
runs.started boolean yes whether a started of its login counts
runs.in_care boolean no whether this actor has its run in care; absent on the served repository
runs.note string no why it waits, or why its actor would refuse it, as its check would decide now; absent when neither
runs.release string (check-in) no the release its actor ran it on, $$release$$ in its started; absent before its started
runs.current boolean no whether that release is the one served now; a run on another keeps it until it is stopped and sent again
runs.hears list of string no for a session, the users whose posts and ticket changes it is given; absent for any other run
runs.checkins list of string no for a session, the branches whose check-ins it is given; absent for any other run
runs.processes list of object no for setup, the processes now running in its sandbox on this host, read from /proc: each its watcher's descendant, after its parent; none when its actor holds none
runs.processes.pid integer yes its number on this host
runs.processes.command list of string yes its command line, as /proc/PID/cmdline gives it, each argument apart; empty for one that has ended and is not yet waited for
runs.processes.started string yes when it started, from its start after the host's boot in /proc/PID/stat
runs.processes.state string yes its state, the letter /proc/PID/stat gives: R running, S sleeping, D waiting on a device, T stopped, Z ended and not yet waited for
projects object no in a release root, for setup, the imports running beside the served repository and the last outcome of one the web page started; absent otherwise
projects.running list of object yes the imports running now beside the served repository, each the process its directory names, as /proc shows it
projects.running.name string yes the new repository's name
projects.running.pid integer yes the process importing, by its number on this host
projects.running.since string yes when the directory it works in was taken for it, in UTC
projects.running.work string yes the directory it works in, beside the served repository
projects.left list of string yes the directories beside the served repository of imports whose process ended without releasing them, as when KILL ended it or its host went down, mostly before it logged an outcome: what such an import made outside its directory, its git export and the new repository, placed or not, stays until the next import of its name, which discards it first, as the directory records it, then clears the directory
projects.last object no the last outcome in the import log, of an import the web page started; absent before the first, or when its last line does not read as one
projects.last.when string yes when it started, in UTC
projects.last.repository string yes the served repository, beside which the new one goes
projects.last.name string yes the new repository's name
projects.last.took_ms number yes how long it took, in milliseconds
projects.last.ok boolean yes true when it made the new repository; false when it stopped, leaving nothing
projects.last.stopped string no why it stopped; absent when it made the new repository
daemon object no the daemon's last round, when this machine keeps its log
daemon.when string yes when this round began
daemon.clone string yes the clone pulled
daemon.completion integer yes the highest receipt after the complete pull
daemon.new integer yes how many new messages were read
daemon.handed list of string yes the runs handed to watchers
daemon.settled integer yes how many runs are settled
daemon.passed list of string yes newly read runs passed by this round because their to or clone names another actor, or neither names one
daemon.failure string no why this round failed, when it did
daemon.listing_failure string no why the optional clone listing could not be shared at start

echo

Answer with exactly the arguments it was given and who gave them, changing nothing. It shows that every entry point delivers the same input.

capabilities needed: (none)

required · a word, given as a bare word
optional · a value, given after the option's name; absent when not given

output

name type required description
word string yes the word as read
option string no the option's value as read; absent when not given
flag boolean yes the switch as read
entry_point one of cli, cgi, mcp, git yes the entry point it was called from: cli, cgi or mcp
login string no the user that called; absent when none is known
capabilities string (fossil-capabilities) yes that user's Fossil capabilities

context

name type required description
entry_point one of cli, cgi, mcp, git yes how the program was entered: cli, cgi or mcp, the entry points to the tools; or git, serving a repository's git export to git clients, neither of which reaches a tool
preview boolean yes whether this program is the pre-release candidate, run from the release offered as next
login string no the user acting; absent when none is known
capabilities string (fossil-capabilities) yes the user's Fossil capabilities; none when no repository says
repository string no the repository acted on; absent when there is none
checkout string no the checkout the caller is in; absent outside one
dir string yes the directory the caller runs in, where relative names start
root string no the release root this program was released into; absent when it was not
sources table of string yes where each setting came from
request list of string yes the names of the request fields the web page read
environment list of string yes the names, never the values, of the environment variables present but not read
remote boolean no whether the caller reaches this program from elsewhere: the web page, or MCP over HTTP or a tunnel; a tool that acts on the caller's own files works only where it is not

answer

name type required description
ok boolean yes true when the tool did what was asked: ran to its end, or in a dry run said what it would do; false when it stopped
tool string yes the tool that answered
dry_run boolean yes true when the call only asked what the tool would do, changing nothing
log list of object yes the operations the tool performed, in order: in a dry run, its checks performed and its changes only listed; when the tool stopped, the last one is the one that stopped it
result any no the tool's output; absent in a dry run, and when the tool stopped
stopped string no why the tool stopped, or in a dry run why it would; absent when it ran, or would run, to the end
next_step string no when the tool stopped, what to do instead, in one line; absent when it ran to its end, or its reason says
took_ms number yes how long the call took, from the program's start to this answer, in milliseconds

read_clone_users: read clone users from every run, published clones and this host's daemon entries

name type required description
op string no the operation
changes boolean no false: a check reads what the run needs, in a dry run too

read_run_address: read the local daemon's clone and user for this project; no default when none exists or several match

name type required description
op string no the operation
changes boolean no false: a check reads what the run needs, in a dry run too
repository string yes the repository holding the run
root string no the local daemon's release root; absent on another machine

read_published_clone: read the recipient's one clone from its public unversioned ocx-clones/LOGIN/SERVER-CODE.json file

name type required description
op string no the operation
changes boolean no false: a check reads what the run needs, in a dry run too

find_where: find a thread or ticket in the repository by a hash or a prefix of one: a ticket by its id or any of its changes, or a thread by any of its posts

name type required description
op string no the operation
changes boolean no false: a check reads what the run needs, in a dry run too
repository string yes the repository
given string yes the thread or ticket as given: a ticket's id, a ticket change's or a forum post's hash, or a prefix of one

find_post: find the post replied to by its hash or a prefix of it, read from its artifact, and the thread it is in

name type required description
op string no the operation
changes boolean no false: a check reads what the run needs, in a dry run too
given string yes the post as given

find_run: find a run in the repository by its hash or a prefix of it: the post or ticket change that holds it, the user its to asks to act, and the clone it names

name type required description
op string no the operation
changes boolean no false: a check reads what the run needs, in a dry run too
repository string yes the repository
given string yes the run as given: its hash, or a prefix of it
upto integer no the last completed pull; absent on the served repository

read_completion: read the daemon's last completed pull of this clone, refusing a clone never pulled whole

name type required description
op string no the operation
changes boolean no false: a check reads what the run needs, in a dry run too
repository string yes the clone
root string yes the release root

read_hook: read Fossil's export hook, other after-receive programs, backoffice settings and the timeline chat user

name type required description
op string no the operation
changes boolean no false: a check reads what the run needs, in a dry run too
repository string yes the repository

read_server_code: read the repository's server-code, which a run names in its clone for OCX on this repository alone to act on (docs/protocol-v2-draft.md, section 2.4)

name type required description
op string no the operation
changes boolean no false: a check reads what the run needs, in a dry run too
repository string yes the repository

read_runs: read runs from the record for every clone user an administrator named, or the actor with its local care and processes

name type required description
op string no the operation
changes boolean no false: a check reads what the run needs, in a dry run too
repository string yes the repository or clone
root string no the release root, when known
processes boolean yes whether local processes are read too
ended boolean yes whether ended runs are read too

read_projects: read the imports running beside the served repository, each the process its directory names, as /proc shows it, the directories of those whose process ended without releasing them, and the last outcome in the import log

name type required description
op string no the operation
changes boolean no false: a check reads what the run needs, in a dry run too
served string yes the served repository
root string yes the release root, whose care directory holds the import log

read_offer: read the actor's offer: its user, clone server-code and enforced limits

name type required description
op string no the operation
changes boolean no false: a check reads what the run needs, in a dry run too
repository string yes the acting clone
login string yes the clone user signed in to the server

read_releases: read which release the root serves and offers

name type required description
op string no the operation
changes boolean no false: a check reads what the run needs, in a dry run too
root string yes the release root

check_committed: check that a Fossil checkout has every change committed, and name the release after its check-in

name type required description
op string no the operation
changes boolean no false: a check reads what the run needs, in a dry run too
checkout string yes the checkout

read_targets: read which programs a checkout's shard.yml builds from tools/

name type required description
op string no the operation
changes boolean no false: a check reads what the run needs, in a dry run too
checkout string yes the checkout

find_offered: find the release the staged area offers as next, unless it is already served

name type required description
op string no the operation
changes boolean no false: a check reads what the run needs, in a dry run too
root string yes the release root

check_first_release: check that the root serves no release yet: the pre-release candidate accepts only an actor's first release, trusted on first use

name type required description
op string no the operation
changes boolean no false: a check reads what the run needs, in a dry run too
root string yes the release root

check_staged_release: check that the staged release is whole: every file its inventory lists is there and matches, and nothing else is

name type required description
op string no the operation
changes boolean no false: a check reads what the run needs, in a dry run too
root string yes the release root
name string yes the release checked

find_previous: find the release the root served before the current one

name type required description
op string no the operation
changes boolean no false: a check reads what the run needs, in a dry run too
root string yes the release root

fetch_pattern: fetch a pattern: a wiki page of the served repository, its newest version that a user holding admin or setup sent, read there, or in a clone just pulled, by the server's order and its receipt tool's word; or the text at an http or https URL; whose first fenced JSON block holds the fields a run starts from

name type required description
op string no the operation
changes boolean no false: a check reads what the run needs, in a dry run too
url string yes the pattern: a wiki page of the served repository by its name, or an http or https URL, read without signing in
repository string yes the served repository, whose own wiki pages are read in it; or a clone, just pulled, whose pages are read there
server string no for a clone, the server it syncs with, by its URL: its pages are its, and its receipt tool, asked unsigned, says who sent each version and in what order; absent on the served repository

check_import: check the owner-written builders.json, the run's pattern, address and sender, its first counted reports, every shared file and inventory, and that its staged name is free

name type required description
op string no the operation
changes boolean no false: a check reads what the run needs, in a dry run too
root string yes the release root
run string yes the stage run's full hash
program string yes the program a release of which it is

read_served_release: read current and previous and their inventories; optionally read one listed file, base64

name type required description
op string no the operation
changes boolean no false: a check reads what the run needs, in a dry run too
root string yes the release root
release string no the release to read a file from
file string no the listed file to read

read_follow_release: sign in with the daemon's credentials for this server and read its current release

name type required description
op string no the operation
changes boolean no false: a check reads what the run needs, in a dry run too
root string yes the client's release root
server string yes the served repository's URL

fetch_follow_release: check every SHA-256, fetching listed files absent from the client's release

name type required description
op string no the operation
changes boolean no false: a check reads what the run needs, in a dry run too
root string yes the client's release root
name string yes the release to fetch

decide_run: decide the manual run on this acting clone, reading its server's receipts and local care

name type required description
op string no the operation
changes boolean no false: a check reads what the run needs, in a dry run too
repository string yes the clone
run string yes the run's full hash
root string yes the release root
completion integer yes the last completed pull

find_terminal: find the socket of the terminal a run's process is on, in this host's care directory, by the run's hash or a prefix of it

name type required description
op string no the operation
changes boolean no false: a check reads what the run needs, in a dry run too
directory string yes the care directory
given string yes the run as given: its hash, or a prefix of it

read_asked: read every post and ticket change the ocx-message tag was ever put on, whatever its value and whether or not it was cancelled since, its message saying what it is, in the server's order, each with the user the server received it from

name type required description
op string no the operation
changes boolean no false: a check reads what the run needs, in a dry run too
repository string yes the repository

describe_references: describe each link a person is shown, where each question and run is and what a question replies to or refers to: its kind, title, sender, time and excerpt, each hash in it shown by its artifact's title, or cut, only as far as the caller may read it, by one query for the links and one for the hashes their excerpts hold; and each link in full, from the server's public URL

name type required description
op string no the operation
changes boolean no false: a check reads what the run needs, in a dry run too
repository string yes the repository
readable list of string yes the kinds of what a link names that the caller may read
server string no the server whose links are given in full, by its URL, any user or password left out: a clone's remote; absent on the served repository, whose public URL is read

title_notes: show each hash the notes of decisions and runs hold by its artifact's title, or cut, as a reference's excerpt shows one, only as far as the caller may read it, by one query for them all

name type required description
op string no the operation
changes boolean no false: a check reads what the run needs, in a dry run too
repository string yes the repository
readable list of string yes the kinds of what a hash names that the caller may read

resolve_references: resolve each reference given to the one artifact, ticket, tech-note or wiki page it names where the caller is, in its clone or on the served repository, by one query: a hash, a prefix, an id, or a link of the server, whole or from its root; each written as a link from the repository's root, a file's lines on its artifact's page, with its title

name type required description
op string no the operation
changes boolean no false: a check reads what the run needs, in a dry run too
given list of string yes the references, as given
server string no the server whose links are taken, by its URL, any user or password left out: the clone's remote; absent on the served repository, whose public URL is read

read_card: read a card definition and its selected columns from the named repositories

name type required description
op string no the operation
changes boolean no false: a check reads what the run needs, in a dry run too
project string yes the project defining the card
name string yes the card name
repositories list of string yes the repositories to read
viewer string yes the viewer login
now string yes the clock for time spans

ask_receipt_service: ask the receipt service what it received each artifact from, and what one user may do there

name type required description
op string no the operation
changes boolean no false: a check reads what the run needs, in a dry run too
artifacts integer yes how many artifacts are asked of
user string no the user asked of; absent when none is

read_receipts: read which user the served repository received each artifact from, that user's capabilities there, and the receipt's number and the artifact's row number

name type required description
op string no the operation
changes boolean no false: a check reads what the run needs, in a dry run too
repository string yes the repository
artifacts list of string yes the artifacts, by their hashes in full

read_capabilities: read the capabilities a user holds on the served repository, as Fossil grants them, inherited ones included

name type required description
op string no the operation
changes boolean no false: a check reads what the run needs, in a dry run too
repository string yes the repository
user string yes the user

read_wiki_moderation: read whether the served repository holds each wiki edit for a moderator unless its user holds ModWiki (l), as its moderation setup sets it, which no clone holds

name type required description
op string no the operation
changes boolean no false: a check reads what the run needs, in a dry run too
repository string yes the repository

read_ticket_moderation: read whether the served repository holds each ticket change made in its ticket pages for a moderator unless its user holds ModTkt (q), as its moderation setup sets it, which no clone holds

name type required description
op string no the operation
changes boolean no false: a check reads what the run needs, in a dry run too
repository string yes the repository

read_remote: read the server a clone syncs with, by its URL, as Fossil's remote names it

name type required description
op string no the operation
changes boolean no false: a check reads what the run needs, in a dry run too
checkout string yes the clone's checkout

ask_server_receipts: ask the server's own receipt tool, unsigned, as anyone may: what it received each artifact from, and what one user may do there

name type required description
op string no the operation
changes boolean no false: a check reads what the run needs, in a dry run too
server string yes the server, by its URL, any user or password left out
artifacts integer yes how many artifacts are asked of
user string no the user asked of; absent when none is

find_checkin: find the check-in by its hash, a prefix of it or a name, and the user who checked it in

name type required description
op string no the operation
changes boolean no false: a check reads what the run needs, in a dry run too
given string yes the check-in as given

check_not_author: check that the verdict comes from someone other than the check-in's author

name type required description
op string no the operation
changes boolean no false: a check reads what the run needs, in a dry run too
author string yes the check-in's author
login string yes the user giving the verdict

read_verdict: read the verdict back as the served repository holds it: there, from its tags; from a clone, by a second push that must send nothing

name type required description
op string no the operation
changes boolean no false: a check reads what the run needs, in a dry run too
checkin string yes the check-in
checkout string no the clone's checkout it was made in; absent when it was made on the served repository

read_unaudited: read the check-ins that change files, and every verdict's tag change with who sent it, by the served repository's receipts; keep the check-ins no verdict that counts has judged, in the order it received them

name type required description
op string no the operation
changes boolean no false: a check reads what the run needs, in a dry run too
repository string yes the repository
branch string no the branch read; every branch when absent

ask_server_unaudited: ask the server's own unaudited tool, unsigned, as anyone may, which counts verdicts by its own receipts

name type required description
op string no the operation
changes boolean no false: a check reads what the run needs, in a dry run too
server string yes the server, by its URL, any user or password left out
branch string no the branch asked of; every branch when absent

read_approval: read what the served repository keeps for a login an admin approved: its code's key and its password; none unless the user is there still holding that password, so a user made again by hand is not taken for it

name type required description
op string no the operation
changes boolean no false: a check reads what the run needs, in a dry run too
login string yes the login

collect_password: ask the server's collect for the login's password, giving its code; none while no admin has approved the login

name type required description
op string no the operation
changes boolean no false: a check reads what the run needs, in a dry run too
server string yes the server
login string yes the login asked for

sign_in: sign in to the server as the login its file of passwords names, through Fossil's login page, and check that the server has that user, holding neither admin nor setup (docs/protocol-v2-fossil.md, section 5)

name type required description
op string no the operation
changes boolean no false: a check reads what the run needs, in a dry run too
server string yes the server's URL
credentials string yes the actor's file of passwords, by its path; never what it holds

find_export: find the repository's git export where its last-git-export-repo setting says, and read where it stands, as fossil git status says, with OCX's last run of it

name type required description
op string no the operation
changes boolean no false: a check reads what the run needs, in a dry run too
repository string yes the repository

check_project: check the daemon's care directory, when the daemon is on this machine, the new repository's name, that nothing of that name is served or exported yet, and where the upstream is

name type required description
op string no the operation
changes boolean no false: a check reads what the run needs, in a dry run too
name string yes the new repository's name
upstream string no the upstream: a git repository's URL, or its directory here
served string yes the served repository, beside which the new one goes
mirrors string no the directory of git exports that the new one's export goes in; absent for the one that holds the served repository's export
daemon_root string no the ocx2 daemon's release root, when the daemon is on this machine; absent when its actor joins from another

read_served_setup: read what the new repository takes from the served one: this release's hook, if it is installed there, and its public URL

name type required description
op string no the operation
changes boolean no false: a check reads what the run needs, in a dry run too
served string yes the served repository
name string yes the new repository's name

read_save_state: read the checkout's changes, the branch it is on, the tests its project names, and which passed with the checkout as it is now

name type required description
op string no the operation
changes boolean no false: a check reads what the run needs, in a dry run too

read_bundle: read the agent's bundle: each check-in it holds, the branch it is on and its comment, importing nothing

name type required description
op string no the operation
changes boolean no false: a check reads what the run needs, in a dry run too
file string yes the bundle, as written to a file in a scratch directory

pull_and_export: pull the server into the clone, and bundle every check-in after the one the agent has

name type required description
op string no the operation
changes boolean no false: a check reads what the run needs, in a dry run too
have string yes the check-in the agent has
file string yes the bundle's file

confirm_landed: find each pushed check-in by its hash in full, and ask the server's receipt tool who it received each from

name type required description
op string no the operation
changes boolean no false: a check reads what the run needs, in a dry run too
pushed list of string yes the check-ins pushed, as the bundle lists them

bundle_branch: bundle every check-in on the working branch, whole, base64

name type required description
op string no the operation
changes boolean no false: a check reads what the run needs, in a dry run too
branch string yes the working branch

read_context: read the run the checkout's workspace is named for, the branch the checkout is on, its changed and new files, and the tests its project names

name type required description
op string no the operation
changes boolean no false: a check reads what the run needs, in a dry run too

find_text: search the checkout's text files under a path for each line holding a text, exactly

name type required description
op string no the operation
changes boolean no false: a check reads what the run needs, in a dry run too
text string yes the text
under string yes the path searched under

read_lines: read lines of a file in the checkout, exactly as they are

name type required description
op string no the operation
changes boolean no false: a check reads what the run needs, in a dry run too
path string yes the file, by its path from the checkout's root
from integer yes the first line read

read_whole: read a file of the checkout whole, or find it absent

name type required description
op string no the operation
changes boolean no false: a check reads what the run needs, in a dry run too
path string yes the file, by its path from the checkout's root

read_wiki_page: read the newest version of a wiki page in the clone

name type required description
op string no the operation
changes boolean no false: a check reads what the run needs, in a dry run too
name string yes the page's name

list_unversioned: list the clone's unversioned files: each name, the hash of its content and its size

name type required description
op string no the operation
changes boolean no false: a check reads what the run needs, in a dry run too

read_unversioned: read an unversioned file's content from the clone, base64

name type required description
op string no the operation
changes boolean no false: a check reads what the run needs, in a dry run too
name string yes the file's name

ask_server_capabilities: ask the server's receipt tool what the clone's user may do there, since Fossil passes over unversioned files a user may not write and says nothing

name type required description
op string no the operation
changes boolean no false: a check reads what the run needs, in a dry run too
user string yes the user

read_own_capabilities: read the capability letters a user of the served repository holds of its own, not those Fossil's own users lend it

name type required description
op string no the operation
changes boolean no false: a check reads what the run needs, in a dry run too
user string yes the user

read_thread: read every post of the thread, or every change to the ticket that adds text, in the order the repository received them

name type required description
op string no the operation
changes boolean no false: a check reads what the run needs, in a dry run too
record string yes the thread, by its first post, or the ticket, by its id
repository string yes the repository read

read_conversation: read the name a person gave the thread, the raw tag console-name on its first post, as it is now

name type required description
op string no the operation
changes boolean no false: a check reads what the run needs, in a dry run too
root string yes the thread, by its first post
repository string yes the repository read

start_project: take the directory the import works in, as take_work does, for the import it starts there, detached, as the hook starts a watcher: this release's program, given that directory, which holds what it imports, its output in the care directory, so the web page answers at once; the import writes its outcome in the import log, beside the hook's, which status shows with the imports running

name type required description
op string no the operation
changes boolean no true: a change is performed only for real; a dry run lists it
work string yes the directory the import works in
repository string yes the new repository, which must not be there yet
program string yes the program started: this release's, the current one or, from the preview, the one offered as next

take_work: take the directory the import works in, beside the served repository, for this process, which it names there: refused while another import's process named there runs; made anew by an exclusive create where an import that ended left it, but kept as it was left where it records what that one made outside it, for discard_left; taken already when the web page started this process to import (start_import), which then releases it once its outcome is logged

name type required description
op string no the operation
changes boolean no true: a change is performed only for real; a dry run lists it
work string yes the directory the import works in
repository string yes the new repository, which must not be there yet

discard_left: discard what an import of this name that ended unasked, as KILL ends one, made outside the directory it worked in, as that directory records it: its git export, and the new repository, out of its login group first; then clear the rest it left there, but the process named; refused, saying why, where that repository cannot leave its group, and where the repository or export is there, unrecorded

name type required description
op string no the operation
changes boolean no true: a change is performed only for real; a dry run lists it
work string yes the directory the import works in, as the import that ended left it
discarded list of string yes what that import made outside it, as the directory records it: its git export, the new repository, or both

run_gate: run a checkout's own checks (crystal run ci.cr), writing what they print to its log as it comes, and answer the gate's note

name type required description
op string no the operation
changes boolean no true: a change is performed only for real; a dry run lists it
checkout string yes the checkout
log string yes where what the gate prints is written as it runs, so a long gate can be followed

run_build: build a checkout's programs (shards build)

name type required description
op string no the operation
changes boolean no true: a change is performed only for real; a dry run lists it
checkout string yes the checkout

copy_release: copy a checkout's built programs into a release in the staged area, with the gate's note, where the source is, and its inventory

name type required description
op string no the operation
changes boolean no true: a change is performed only for real; a dry run lists it
checkout string yes the checkout, whose bin/ holds the programs
release string yes the release's directory: the staged area's, named for the check-in
programs list of string yes the programs copied

smoke_release: run a release's program with no arguments and an empty environment, and require it to print its usage

name type required description
op string no the operation
changes boolean no true: a change is performed only for real; a dry run lists it
release string yes the release's directory
program string yes the program run

offer_release: point the staged area's next at a release, the pre-release candidate, which ocx2-cgi-next runs

name type required description
op string no the operation
changes boolean no true: a change is performed only for real; a dry run lists it
staged string yes the staged area
name string yes the release offered

take_release: copy a staged release into the root, checking every file against its inventory

name type required description
op string no the operation
changes boolean no true: a change is performed only for real; a dry run lists it
root string yes the release root
name string yes the release taken

serve_release: point the root's current at an accepted release, which ocx2-cgi then runs, and previous at the release it replaces

name type required description
op string no the operation
changes boolean no true: a change is performed only for real; a dry run lists it
root string yes the release root
name string yes the release served
replaces string no the release served before, which becomes previous; absent for a first release, trusted on first use

roll_back: serve the previous release again, which ocx2-cgi then runs, keeping the release it replaces as previous

name type required description
op string no the operation
changes boolean no true: a change is performed only for real; a dry run lists it
root string yes the release root
name string yes the release served again
replaces string no the release served before, which becomes previous; absent if none

start_ticket: start a ticket, Open, on the served repository as the caller, and name it and its first change

name type required description
op string no the operation
changes boolean no true: a change is performed only for real; a dry run lists it
title string yes the ticket's title
user string yes the caller, whose ticket it is

append_to_ticket: append to the ticket's comment as the caller, in the caller's clone and pushed, or on the served repository as the viewer, and name the new change

name type required description
op string no the operation
changes boolean no true: a change is performed only for real; a dry run lists it
ticket string yes the ticket's id
user string yes the caller, whose change it is
checkout string no the clone's checkout it is made in; absent when it is made on the served repository

write_thread: write the run as the first post of a new thread, as the caller on the served repository

name type required description
op string no the operation
changes boolean no true: a change is performed only for real; a dry run lists it
title string yes the thread's title
user string yes the caller, whose post it is

write_reply: write a reply to the post, in its thread, as the caller on the served repository

name type required description
op string no the operation
changes boolean no true: a change is performed only for real; a dry run lists it
thread string yes the thread, by its first post
to string yes the post replied to
user string yes the caller, whose post it is

copy_import: copy the three counted files into staged/NAME, check the inventory and smoke the program with no arguments

name type required description
op string no the operation
changes boolean no true: a change is performed only for real; a dry run lists it
root string yes the release root
name string yes the check-in's first twelve hex digits
program string yes the program smoked

remove_release_files: remove this run's program, release.txt and gate.txt unversioned files from the served repository

name type required description
op string no the operation
changes boolean no true: a change is performed only for real; a dry run lists it
run string yes the stage run's full hash
program string no the program whose files they are

take_follow_release: put the checked release into the client's root as accept does

name type required description
op string no the operation
changes boolean no true: a change is performed only for real; a dry run lists it
root string yes the client's release root
name string yes the release taken

hand_run: hand the manual run to this release's watcher with its clone and explicit server credentials

name type required description
op string no the operation
changes boolean no true: a change is performed only for real; a dry run lists it
repository string yes the clone
root string yes the release root
run string yes the run's full hash

write_stop: write the stop where the run is, as the caller on the served repository: a reply to the run's post in its thread, or a change to its ticket

name type required description
op string no the operation
changes boolean no true: a change is performed only for real; a dry run lists it
run string yes the run's post or ticket change
kind string yes forum or ticket
record string yes the run's thread, by its first post, or its ticket
user string yes the caller, whose stop it is

join_terminal: join your terminal to the terminal of a run's process until you press Ctrl-]: you see what it shows and type into it, and it goes on when you leave

name type required description
op string no the operation
changes boolean no true: a change is performed only for real; a dry run lists it
socket string yes the terminal's socket

put_post: put the reply into the caller's clone as Fossil's forum artifact, index it there, and push it, so the served repository takes it as a post by the user that pushed it

name type required description
op string no the operation
changes boolean no true: a change is performed only for real; a dry run lists it
thread string yes the thread
to string yes the post replied to
user string yes the caller, whose post it is
checkout string yes the clone's checkout it is put in

tag_checkin: tag the check-in audited with the verdict and the note, as the caller, in the caller's clone and pushed, or on the served repository as the viewer

name type required description
op string no the operation
changes boolean no true: a change is performed only for real; a dry run lists it
checkin string yes the check-in
value string yes the tag's value: the verdict, a colon, the note, and what it was judged against
login string yes the caller, whose verdict it is
checkout string no the clone's checkout it is made in; absent when it is made on the served repository

set_secret: set the secret on the served repository, a setting of its own that Fossil never syncs or clones, its value shown nowhere

name type required description
op string no the operation
changes boolean no true: a change is performed only for real; a dry run lists it
name string yes the secret's name

approve_login: make the login asked for, or set the one approve made before, holding exactly the capabilities asked, with a random password the served repository keeps with the code's key, apart from its secrets, for the asker to collect, never shown; the same password when approved again for the same code; for another code, a new one, and the earlier holder's stops working

name type required description
op string no the operation
changes boolean no true: a change is performed only for real; a dry run lists it
login string yes the login
capabilities string (fossil-capabilities) yes the capabilities it holds
there boolean yes whether the user was there already

make_run_user: make a user for the run's process on the served repository, holding only what a run's user needs, its random password kept for the run's clone user to collect and never shown

name type required description
op string no the operation
changes boolean no true: a change is performed only for real; a dry run lists it
user string yes the user made
login string yes the clone user approved to collect its password
capabilities string yes its capabilities
by string yes who made it, as its contact information says

approve_run_user: approve a kept run user's password for the run's clone user to collect, setting a new random password only when asked

name type required description
op string no the operation
changes boolean no true: a change is performed only for real; a dry run lists it
user string yes the run's user
login string yes the clone user approved to collect
reset boolean no whether a new random password was explicitly requested

make_code: make the code the login is approved by, and keep it with the login and the capabilities asked in the file of passwords, readable by its owner alone

name type required description
op string no the operation
changes boolean no true: a change is performed only for real; a dry run lists it
login string yes the login asked for
capabilities string (fossil-capabilities) yes the capabilities asked for
credentials string yes the file of passwords

keep_password: keep the login's password in the file of passwords in place of the code, readable by its owner alone

name type required description
op string no the operation
changes boolean no true: a change is performed only for real; a dry run lists it
credentials string yes the file of passwords

clone_server: make the acting clone of the server, signed in as the clone's user

name type required description
op string no the operation
changes boolean no true: a change is performed only for real; a dry run lists it
repository string yes the clone
user string yes the clone's user

prepare_clone: name the actor's default user and keep the clone's default remote as the named remote used for complete pulls, verdicts and shares

name type required description
op string no the operation
changes boolean no true: a change is performed only for real; a dry run lists it
repository string yes the acting clone
user string yes the clone's user

watch_run: watch the run under its lock, deciding again and posting reports through Fossil's pages

name type required description
op string no the operation
changes boolean no true: a change is performed only for real; a dry run lists it
repository string yes the clone
root string yes the release root
run string yes the run's full hash
by_hand boolean yes whether a person starts this manual run

delete_hooks: delete Fossil's export command and any old ocx2-hook command, leaving other hooks

name type required description
op string no the operation
changes boolean no true: a change is performed only for real; a dry run lists it
repository string yes the repository

add_hook: add the hook to the repository's hooks, for Fossil's backoffice to run after each receipt

name type required description
op string no the operation
changes boolean no true: a change is performed only for real; a dry run lists it
repository string yes the repository
command string yes the command Fossil runs, the repository in place of %R

export_to_git: export the check-ins waiting, with fossil git export, one run at a time: while another run holds the export, ask it to export again instead; it exports until no run asks

name type required description
op string no the operation
changes boolean no true: a change is performed only for real; a dry run lists it
mirror string yes the export's directory
awaiting integer no how many check-ins wait to be exported; absent when Fossil cannot say, and the export mends that
autopush string no where Fossil pushes after each export, or off
failed string no why Fossil cannot say where the export stands, else why the last run failed; absent when neither

clone_project_upstream: clone the upstream bare, in a sandbox, since an upstream may be anyone's

name type required description
op string no the operation
changes boolean no true: a change is performed only for real; a dry run lists it
upstream string yes the upstream
work string yes the directory the import works in, taken for it

new_project: make an empty Fossil repository with the project's name and the caller as admin

name type required description
op string no the operation
changes boolean no true: a change is performed only for real; a dry run lists it

empty_project_export: reserve the empty project's git export and record it for cleanup

name type required description
op string no the operation
changes boolean no true: a change is performed only for real; a dry run lists it

set_project_tickets: give the new repository's tickets milestone and due fields

name type required description
op string no the operation
changes boolean no true: a change is performed only for real; a dry run lists it

ready_project: file clone and process passwords privately, making their users and letting the daemon find the project by its password file

name type required description
op string no the operation
changes boolean no true: a change is performed only for real; a dry run lists it

project_branches: write the upstream's branches as a git fast-export stream with its marks, naming its own branch trunk as Fossil does, straight into Fossil's import, which makes a new repository with Fossil's marks, through a pipe, never a file; git and fossil each in a sandbox of its own; the tags stay git's

name type required description
op string no the operation
changes boolean no true: a change is performed only for real; a dry run lists it
work string yes the directory the import works in
admin string yes the new repository's admin, the caller

seed_project_export: make the new repository's git export from the upstream's clone, its state seeded with each check-in and the upstream commit it is, so the upstream's commits keep their ids and what Fossil adds exports on top of them; its directory made by an exclusive create, and recorded in the directory the import works in once made

name type required description
op string no the operation
changes boolean no true: a change is performed only for real; a dry run lists it
work string yes the directory the import works in
mirror string yes the git export made
main_branch string yes the git branch Fossil's trunk exports as: the upstream's own

export_project: export the new repository once, in the directory the import works in, which records its export and adds nothing; the export's git configuration keeps the upstream's URL

name type required description
op string no the operation
changes boolean no true: a change is performed only for real; a dry run lists it
repository string yes the new repository, in the directory the import works in
mirror string yes its git export

set_public_url: set the new repository's public URL, its email-url, for its administrator, the caller: the served one's with its own name, so it is ready to use and a run's clone can be made from it with no step by hand

name type required description
op string no the operation
changes boolean no true: a change is performed only for real; a dry run lists it
repository string yes the new repository, in the directory the import works in
url string yes its public URL

copy_patterns: copy the served repository's patterns, its wiki pages run/NAME, into the new one, so runs are written there as on the served one

name type required description
op string no the operation
changes boolean no true: a change is performed only for real; a dry run lists it
served string yes the served repository
repository string yes the new repository, in the directory the import works in
pages list of string yes the pages copied: the patterns that a user holding admin or setup wrote
admin string yes who writes them: the new repository's admin, the caller

hook_project: install the hook on the new repository as this release's is installed on the served one, so its export is kept current

name type required description
op string no the operation
changes boolean no true: a change is performed only for real; a dry run lists it
repository string yes the new repository, in the directory the import works in
hook string yes the hook's command, as this release installs it on the served repository

place_project: place the new repository beside the served one, made in the directory the import works in with all but its login group, by one rename, recorded in that directory first, so it is never placed unrecorded: should the import end unasked before it is in the group, as KILL ends one, the next import of its name discards it

name type required description
op string no the operation
changes boolean no true: a change is performed only for real; a dry run lists it
work string yes the directory the import works in
repository string yes the new repository's place, beside the served one

join_login_group: join the new repository to the served one's login group, made of the two and named for the served one when it is in none, so signing in to the served repository signs the caller in to the new one, where the caller is admin

name type required description
op string no the operation
changes boolean no true: a change is performed only for real; a dry run lists it
repository string yes the new repository
served string yes the served repository

commit_work: track the checkout's new files and commit every change on the working branch, starting it if the checkout is on another, without syncing

name type required description
op string no the operation
changes boolean no true: a change is performed only for real; a dry run lists it
branch string yes the working branch
message string yes the check-in's comment

import_and_push: import the agent's bundle into the clone, its check-ins public, and push them to the server as the clone's user

name type required description
op string no the operation
changes boolean no true: a change is performed only for real; a dry run lists it
file string yes the bundle's file
checkins list of string yes the check-ins it holds, by their hashes as the bundle gives them

write_file: write a file of the checkout whole, making its directory if it has none

name type required description
op string no the operation
changes boolean no true: a change is performed only for real; a dry run lists it
path string yes the file, by its path from the checkout's root
bytes integer yes how many bytes it holds

run_test: run a test the project names, in the checkout, within its wall clock, and record whether it passed with the checkout as it is

name type required description
op string no the operation
changes boolean no true: a change is performed only for real; a dry run lists it
name string yes the test's name
command list of string yes its command

push_work: push the clone's check-ins to the server as its user

name type required description
op string no the operation
changes boolean no true: a change is performed only for real; a dry run lists it

pull_clone: pull the server into the clone, so what is read is the server's newest; refused when the pull does not reach it

name type required description
op string no the operation
changes boolean no true: a change is performed only for real; a dry run lists it

write_wiki_page: write a new version of a wiki page in the clone, or the page itself when it is new, and push it as the clone's user

name type required description
op string no the operation
changes boolean no true: a change is performed only for real; a dry run lists it
name string yes the page's name
new boolean yes whether the page is new

sync_unversioned: sync the clone's unversioned files with the server's, as the clone's user: send what the server lacks, take what it has newer

name type required description
op string no the operation
changes boolean no true: a change is performed only for real; a dry run lists it

put_unversioned: keep content as an unversioned file of the clone

name type required description
op string no the operation
changes boolean no true: a change is performed only for real; a dry run lists it
name string yes the file's name
size integer yes its size in bytes

keep_connector_key: keep the SHA-256 of the connector's new key for the login it acts as, not yet approved, replacing any kept for it, in a config row, and its issuer's metadata as an unversioned file, where a client looks for it; or remove both, so no key acts as that login; the key itself is kept nowhere

name type required description
op string no the operation
changes boolean no true: a change is performed only for real; a dry run lists it
login string yes the login the key acts as
revoked boolean yes whether the key is removed

add_own_capability: add a capability letter to those a user of the served repository holds of its own, unless they hold it, in one statement, leaving every other letter as it is then, so one another writer gave the user since they were read stays

name type required description
op string no the operation
changes boolean no true: a change is performed only for real; a dry run lists it
user string yes the user
capability string (fossil-capabilities) yes the letter added

remove_own_capability: take a capability letter out of those a user of the served repository holds of its own, in one statement, leaving every other letter as it is then, so one another writer gave the user since they were read stays

name type required description
op string no the operation
changes boolean no true: a change is performed only for real; a dry run lists it
user string yes the user
capability string (fossil-capabilities) yes the letter taken out, every one of it

keep_app_builders: keep, in a config row of the served repository, the stage pattern and the builder whose runs import may take as releases of the app, replacing any kept before

name type required description
op string no the operation
changes boolean no true: a change is performed only for real; a dry run lists it
app string yes the app

tag_untagged: read every post and ticket change holding an OCX message, as the actor's check reads them, and tag each that lacks the ocx-message tag, or carries another value, in one control artifact, as the caller: on the served repository, or in the caller's clone and pushed

name type required description
op string no the operation
changes boolean no true: a change is performed only for real; a dry run lists it
user string yes the caller, whose tags they are
checkout string no the clone's checkout it is made in; absent when it is made on the served repository

releases

ROOT/staged/NAME/

ROOT/staged/next

ROOT/NAME/

ROOT/current

ROOT/previous