DocumentationCommand line
Running ropeshift
Command line
On this page
ropeshift is a client of the versioned API, so it reaches the ledger the same way every other surface does. It finds the control plane's socket from the installation's paths, or from --socket.
A command that changes something needs a member's session, and a read on the local socket does not. With no session, the command asks for the passphrase on the terminal, for that one command. eval "$(ropeshift login)" holds a short-lived session in one shell instead. No file holds it, and no lane inherits it. The passphrase comes only from the controlling terminal, never from stdin, a flag, or a variable, so a process with no terminal cannot sign in.
Every command takes --json. With it, a result is one JSON document on stdout, and a failure is {"error": {...}} on stderr with the same exit code.
Help#
ropeshift help, ropeshift --help, and ropeshift -h list every command by group, each with one line, on stdout, and exit 0. ropeshift help <command> and ropeshift <command> --help print one command's usage, what it does, and its flags, and exit 0. A group's first word lists the commands under it, so ropeshift help work lists every work command.
ropeshift with no command prints the same list on stderr and exits 2: a missing command is a usage error, as an unknown one is. An unknown command or flag exits 2 and names ropeshift help. ropeshift --version is ropeshift version, and ropeshift --version --json prints its JSON.
ropeshiftd answers the same forms for its own commands: solo, help, and version.
Projects#
An installation holds one or more projects, and each project's records live in a ledger of their own. A command on a project's records acts on one project, which it takes from the first of these that names one:
--project <name>.ROPESHIFT_PROJECT.- The project that holds the repository the command runs in: its remote, with no credential and no
.gitsuffix, or its first commit when it has no remote. - The only active project.
With none of these, the command exits 2 and lists the projects. A name the installation does not hold exits 2 with the same list.
Every step of a project's lifecycle needs a member's session and records an event in the installation's log, with who took it.
A repository belongs to one project. Its identity is its remote, or its first commit when it has none, so every clone of one repository is the same repository. Registering a repository another project holds is refused with exit 4, and the message names that project.
Each repository has a name, unique in its project. A repository gets the name of its clone's directory, or the last part of its remote's path when another repository of the project holds that name, and a number after it when both are taken. Every repository command takes the name as well as the identity or a prefix of the identity of 7 or more characters: a whole identity always names its own repository, then a name, then a prefix. So that no name reads as another repository's identity, repository set --name refuses a name of 40 or more hexadecimal digits, the shape of every identity, and a name that is another repository's identity or a prefix of it of 7 or more characters, and automatic naming skips both. Registering a repository whose identity a name of the project spells, whole or as such a prefix, names that repository again as automatic naming would, with a number after its name, and records the change. A contract's repo names the repository a work order changes by that name, and "." or no repo names the repository that holds the contract file. A name the project does not hold is an intake problem that source list reports, and the work order fails the definition of ready, with the check repository, until a repository of the project takes that name.
A project plans in one repository, its planning repository. A project of one repository plans in it with nothing to set. A project of several names one with repository set <name> --planning, and naming another moves it. Once a project names one, intake reads goals, plans, documents, milestones, and contracts only from it, and each such file in another repository of the project is a problem that source list reports, so a plan in the wrong repository is seen and never read. A project of several repositories that names none reads plan files from every one of them.
The commands on the installation's own records take no project: project, worker, orchestrator, login, sign-out, passphrase, delegate, operation, init, service, health, telemetry, which reads the worker's own store, needs, which reads every active project, and backup --installation.
Delegates#
A delegate is an agent outside ropeshift that a member gave a delegate credential (authorization). A command presents the credential in ROPESHIFT_DELEGATE_TOKEN in place of a session, and a shell that sets both ROPESHIFT_DELEGATE_TOKEN and ROPESHIFT_MEMBER_TOKEN exits 2. A delegate reaches only the project its credential names, so it names that project with --project or ROPESHIFT_PROJECT: finding the project from the repository reads the installation's project list, which a delegate cannot. A command that acts on this machine rather than through the API alone, such as service install, backup, or repository add, exits 8 for a delegate, as does any command that names --socket, and a delegate's command reads no file on this machine: a flag that names one, such as lane start --profile, is refused before the file is read (authorization lists each).
A delegate's command on an operational operation runs as the delegate. One on a consent operation runs nothing unless the delegate policy in force exempts it: it records a confirmation card, prints Prepared card <id>: <title>. It runs only when a member confirms it in Needs you or with ropeshift confirm <id>., and exits 10, and with --json it prints the card. Such a command needs --why <text>, the reason the card shows a member, up to 2,000 characters, and exits 2 without it. A member-only operation exits 8. ropeshift operation list prints the class of each operation.
One worker per machine serves every active project, and one orchestrator per machine serves every active project too. The daemon runs its ticks, intake, and notices in each active project, in that project's own database, and none in an archived project.
Commands#
| Command | Does |
|---|---|
ropeshift needs | Lists what waits on a member in every active project, the longest wait first, each item with its project, its kind, its ID, and how long it has waited. --json prints the combined Needs you |
ropeshift top [--once] [--width N] | Watches the fleet: what needs a person first, in every active project, each item with its project and in the order the combined Needs you holds, then each lane of the project it resolved in that order with its state, reachability, and whether its value is observed or last_reported, then the workers, each with what it last measured of its machine and when. Under each lane's line, a second line carries its context, tokens, and cost, and the CPU and resident memory of its process tree. Each worker's line carries its orchestrator's process tree, the line under it what the worker measured of its machine and the cap in force beside its recommendation, and the next line when it measured, with any warning past a threshold; a measure the machine cannot provide reads unavailable. A confirmation card says what it asks and which delegate prepared it, and names ropeshift confirm and ropeshift decline for it. A parked lane says what it waits for, such as waits for question q-1 or a person. What a need says wraps onto lines under it, in the column it started in, so a long detail is never clipped. It follows the ledger's events and reads again at least every 5 seconds, and it changes nothing: it names the command for what the cursor stands on, with --project for an item of another project. Text from agents and repositories prints with control characters replaced. With no terminal, or with --once, it prints one frame, without the key help, and --json prints one document. A printed frame is as wide as the terminal on stdout, and 120 columns when stdout is not a terminal, such as a pipe or a file. --width N sets its width in columns, and clips any line but a need's to it |
ropeshift health | Says the control plane answered and read its ledger, and the revision the first project stands at, or 0 once the installation removed that project. It exits 9 when nothing answers |
ropeshift project list | Lists the installation's projects, oldest first, each with its state, its display name, how many repositories it holds, and how many things wait on a member in it. --json lists the identity of each repository |
ropeshift project show <name> | Shows one project: its ID, which every record of its ledger carries, its display name, its state, its database, and the record of each repository it holds |
ropeshift project create <name> [--display-name T] | Creates a project with a ledger of its own, at the current schema, and registers it. The name is a lowercase, hyphenated slug no other project holds, used in addresses and --project. The ID is new, so the project's backup imports into any installation |
ropeshift project rename <name> <new-name> | Changes a project's name. Its ID, its database, and every record keep their identity, and the old name names nothing |
ropeshift project archive <name> | Makes a project read-only in every surface: it takes no claims and no change, and the daemon runs no intake, tick, or notice for it. It reads and backs up as before. It is refused, naming the lane, while any lane of the project has not ended, so drain it first with fleet drain. Archiving an archived project changes nothing |
ropeshift project restore <name> | Returns an archived project to active. A project that is not archived exits 4 |
ropeshift project remove <name> --confirm <name> (--backup F | --no-backup) | Deletes an archived project's database and drops it from the registry and the repository index, after writing its backup to F when --backup names a file. It exits 2 unless --confirm repeats the name and exactly one of --backup and --no-backup is given, and 4 for a project that is not archived. The installation's first project is removed like any other |
ropeshift project import <file> [--name N] | Registers a project from its backup, keeping its ID, under --name or the name its backup holds. It exits 4 when the installation holds that ID or name, or when another project holds one of its repositories, which the message names. A relative path is read from where the command runs |
ropeshift version [--json] | Prints the version, the commit, the build date, the Go version, and the platform. It needs no daemon, and ropeshiftd version prints the same under the daemon's name. --version is the same command. See versioning |
ropeshift help [<command>] | Lists every command by group, or prints one command's usage, what it does, and its flags. See help |
ropeshift work create --title T [--criterion C]... | Records a work order and the contract it pins, in contract_review. With an outside delegate's credential it prepares a confirmation card and exits 10, unless the delegate policy exempts work_order.create, because an orchestrator reads a work order's title; the assistant's runs at once. With --kind plan --repository R, its lane writes repository files on its branch, and intake reads them at the commit a member accepts. The files are goals, plans, requirements, specs, architecture documents, experience designs, milestones, contracts, and the repository manifest of the planning repository, and intake keeps a numbered version of each document for every committed change. A contract pins each document it cites to the version at its commit, and a criterion that serves no requirement of its plan keeps the work from ready. A contract names the milestone of its plan it belongs to, which every contract of a plan with milestones must do, and the shared contracts of its plan it uses, and a milestone names the milestones it depends on. Intake makes every work order of a milestone wait for every work order of the milestones it depends on, and every work order of a contract wait for the work orders of each shared contract it uses. A reference to a milestone or shared contract the plan does not hold is a problem, and intake records nothing from that file. A plan whose milestones, shared contracts, or work orders depend on each other in a loop is refused whole, and the problem names the loop. Files can also say what already exists: a requirement with status = "met" and evidence the code already meets, and needs no criterion; a milestone or contract with existing = true is delivered already, a contract so marked has no work orders, and nothing that depends on either waits for it; a contract with work orders in an existing milestone is a problem. A work order's continues names an in-flight branch it finishes, and a plan's [[left_out]] tables record each branch or issue it does not carry, with the reason. A contract's reads names, by their names in the project, other repositories its lanes read beside those its work orders' dependencies target, as onboarding describes. source list names R, and reports a file intake could not read. --agent names the roster agent the work's lane runs as, and a contract file's work order names one in agent, which a planning session proposes and plan approval covers. With none, the roster's default mapping chooses by kind and size: plan runs as reasoning, contract_review as analysis, a review as review, and a change by its size as light-implementation, implementation, or heavy-implementation, with an absent size counted as medium. Work sent back moves one implementation tier up, never into an agent whose approval is per use. Work whose agent is unknown or disabled fails the definition of ready, naming the agent |
ropeshift work list [--state S] [--worker W] | Lists work orders. With --worker, it lists only ready work that worker's manifest can run |
ropeshift work show <id> | Shows one work order, then a pull request line when it lands through one (its number, its state, open, closed, or merged, its head commit, and its address), then the reviews it has had as review lines (the review, its state, and the attempt it judged) and the verdicts that speak for its current attempt as verdict lines (the criterion, pass, fail, or cannot_judge, the reviewer's reasons on one line, and its citations). Each approval of a reviewed commit for merge is an approved line: the commit, who approved it, the merge authority level, and the commit it merged as once it landed. When the verdicts hold the work for a member, a waiting line says what for, and for work in integrating it says what the merge waits on. With --json, the reviews are in judged_by, the verdicts in verdicts, the reason in why, the pull request in pull_request, and the approvals in integrations, beside the work order's own fields. A review work order, which ropeshift makes when a lane completes a change that left a commit, names the work order it judges in reviews and the attempt in reviews_fence. base names the branch its contract file asked to start from, and waiting names why ready work is not claimed: waiting_for_merge for a dependency whose accepted work is not yet in the base branch, dependencies_diverge for dependencies whose accepted work is on separate lines, base_unavailable for a base branch that could not be fetched or does not exist, continued_branch_missing for a branch the work continues that neither the remote nor the checkout holds, and, for a review in a repository that reviews through pull requests, pull_request_pending until the worker has pushed the branch and its pull request is open with the commit under review as its head, and forge_unavailable while that worker's gh is missing or signed out. The reason clears by itself once it no longer holds, and a claim that meets it is refused with exit 4 and the same words |
ropeshift work review <id> | Records a passed review, and the definition of ready decides the move to ready. Work whose contract version an approved plan version lists needs no review of its own, because approving the plan passed it |
ropeshift work acceptance <id> | Shows what a work order's evidence leaves to do, with every artifact and check result linked to it, each branch with the files and lines it changed when its worker measured them, and the reviews and verdicts of its current attempt |
ropeshift work accept <id> | Moves completed work to done. A failed check cannot be accepted, and a criterion no check maps to needs a member, because no agent stands behind a lane's own checks. Work whose review is still open can be accepted, and doing so cancels that review. With review target branch at person_merges, finished work waits for this command, with the review's verdict for each criterion beside it. Through a pull request, and in a repository at person_approves or review_approves, accepted work moves to integrating instead: at person_merges it waits there for your merge on GitHub, and otherwise ropeshift merges it; accepting work already in integrating approves the merge of its reviewed commit, as onboarding describes. A planning branch merges on its plan approval and on nothing else, so accepting planning work in integrating is refused with exit 4, as a planning branch describes |
ropeshift work rework <id> --reason R | Sends completed work back to ready for another attempt, and cancels a review that is still open. Its evidence stays on record and stops counting, and the reason reaches the next attempt's first prompt as why the work came back. A criterion a review failed sends work back without you, until the review has judged it max_review_rounds times |
ropeshift work claim <id> --worker W [--claim-id C] | Claims a work order for a worker. A retry with the same claim ID returns the grant |
ropeshift work release <id> --claim-id C --fence N | Gives back a claim whose lane has not started |
ropeshift work write <id> --claim-id C --fence N [--write-id W] [--lane L --generation G] --payload P | Stores one event under a claim's fence. A retry with the same write ID stores one event, and a stale fence exits 5 with the current one in the message |
ropeshift work reassign <id> --reason R | Ends a lapsed holder's ownership, which moves the fence |
ropeshift work cancel <id> --reason R | Ends a work order for good, from any state that is not terminal, which only a member can do. Any claim ends and the fence moves, so a lane can write nothing more. A parked lane ends at once. A lane with a process stops through the guard when its worker hears, saves what it holds to a ref, and reads as last reported until then. Canceling work that is already canceled changes nothing, and finished or failed work exits 4 |
ropeshift work send-back <id> --reason R | Returns a work order in review to planning, because its contract must change. It voids the review, and the contract's next version returns the work to review |
ropeshift work resolve <id> --reason R | Returns blocked work to ready with its review standing, once whatever stopped the lane is fixed |
ropeshift work replan <id> --reason R | Returns blocked work to planning, which voids its review, because its contract must change. Only a member can take work out of blocked |
ropeshift work retry <id> --reason R | Returns failed work to ready for another attempt. A failed lane leaves its work failed whether or not attempts remain, and nothing retries it on its own. A work order has the attempts [recovery_policy] states in max_attempts, 3 by default, unless it names its own. Work with no attempts left gets one more, which only a member can give. The next attempt's first prompt says why the last lane failed and why the work was retried |
ropeshift adopt [<path>...] [--project P] [--planning NAME] [--worker ID] [--no-attach] | Adopts the project in the repository it runs in, which must hold a commit, and attaches your terminal to the adopt session. It makes the calls a member makes by hand, each one recorded as yours. It uses the project that holds the repository, or else the one --project or ROPESHIFT_PROJECT names, or else a project named after the repository's directory, in lowercase with a hyphen for anything else, and creates that project when the installation has none by the name. It refuses, with exit 4, a repository another project holds when --project names a different one, and a project that already has an approved plan, which plans its next work with plan start. It registers the repository and every clone at or one level below each path, as repository add does, prints what became of each, and goes on when a clone other than this repository is refused. A project of one repository plans in it; a project of several plans in the repository --planning names, or the one the project already plans in, or else asks on the terminal which one holds the plan, and with no terminal stops with exit 2 and the names to choose from. It then creates a plan work order that adopts the project, passes its contract review, claims it on the worker, which is --worker or chosen as plan start chooses one, starts the lane, and attaches as plan start does. The lane is a planning lane whose brief onboards the project's documents and plans what remains, and the worker writes the inventory of every repository of the project into its context folder before it starts. With no terminal, with --no-attach, or with --json, it starts the session and prints the project, the lane, and the lane attach command that joins it |
ropeshift plan start [--goal TEXT | --goal-file PATH] [--worker ID] [--repository R] [--no-attach] | Opens a planning session and attaches your terminal to it. It makes the calls a member makes by hand, each one recorded as yours: it creates a plan work order whose statement is the goal, passes its contract review, claims it on a worker, and starts the lane, then waits for the lane's pane and runs lane attach. The goal is optional, and a session with none starts with the planning agent asking what the plan is for. The worker is --worker, or the only worker registered, or the only one of several whose word is fresh, and otherwise the command lists them and stops. The repository is --repository, or else the project's planning repository, which a member names with repository set --planning and which a project of one repository has by default, or else the one the daemon reads. With no terminal, with --no-attach, or with --json, it starts the session and prints the lane, the lane attach command that joins it, and the session's page in the web UI, at the address the daemon says its web UI listens on, with the port it bound even when --web asked for port 0. It names no page when the web UI is off or the daemon cannot say where it listens. It exits 7 when the review names what still holds the work back, and the work order it recorded stays |
ropeshift plan list | Lists plans |
ropeshift plan show <id> | Shows one plan with its goal, each contract's newest version, and their work orders. When a request to approve the plan stands, it also prints that request: the version, who asked, how the version differs from the last one a member approved, and every draft decision it would decide. The difference names the documents, milestones, and contracts the version adds, changes, and removes, and for a contract that changed, the criteria and work orders it adds, changes, and removes. For a plan that adopts an existing project, it groups the plan into what exists, with each claim's evidence, what continues, what is new, and what is left out, with each reason, and lists every file the adoption branch added, changed, moved, or deleted |
ropeshift plan approve <id> [--version N] | Approves the plan version that waits, in one step, as the member who read it. The version is bound to its digest, so a version that changed since plan show is refused. Approval decides every draft decision of the version as your decision, with a citation to the plan version, and passes the contract review of each work order whose contract version the approved version lists at the same digest, with you as the reviewer. The definition of ready still applies to each, so a question still open keeps the work in review. For a plan a planning lane left on its branch, approval also accepts the lane's plan work order, and intake reads that commit on its next tick. At person_approves and review_approves the approval is also the approval of that branch's merge at the approved commit, and ropeshift merges it once intake has recorded the plan, as a planning branch describes. --version must name the version that waits, and an approved version approves again as the same answer. Only a member with a session can approve a plan; the planning lane that wrote it cannot |
ropeshift plan review <id> [--id I] | Starts a contract review a lane can run, ready for a member to claim. Its lane reads the plan and each contract's newest version, and everything it asks reaches the ladder together when it ends. Its questions are about the plan, so a blocking one holds all of the plan's work. Accepting the review passes the review of the work whose versions it read. With an outside delegate's credential it prepares a confirmation card and exits 10, unless the delegate policy exempts plan.start_review; the assistant's runs at once |
ropeshift requirement list | Lists each requirement's newest version. A requirement whose file says the code already meets it, with status = "met", says so and names the evidence the file cites |
ropeshift requirement get <key> | Shows one requirement's newest version, by the key a contract names |
ropeshift question list [--category C] [--status S] [--scope S] [--text T] | Finds questions. --scope names what a question is about, and --text ranks the best match first |
ropeshift question show <id> | Shows one question |
ropeshift question record --text T [--category C]... [--subject ID] [--subject-kind K] [--blocking] | Records a question as it is, in open. Categories come from category list. --subject-kind is work_order, contract, or plan, and --subject is a record's ID of letters, digits, -, and _; any other exits 2 |
ropeshift question dismiss <id> | Closes a question with no answer. It stays on record |
ropeshift question answer <id> --answer A [--rationale R] [--citation C]... [--id I] | Answers a question that still waits, which records a decision. It works with no orchestrator running, needs no ladder trace, and ends any hold. Every lane attached to the question hears the answer: a running lane as a message, and a parked lane in its next generation's first prompt, which the same answer wakes. A question is answered once, and a second answer exits 4 |
ropeshift question batches [--category C] | Shows the batches that reached members and still wait, each question with its options, recommendation, and citations. Nothing is assigned to anyone. A question from a planning lane skips the ladder and reaches this list at the next batch tick, whatever the window, with the categories its lane named and the options it gave, if any. No orchestrator can take, decide, or assume it, and a member answers it with question answer like any other |
ropeshift decision list [--category C] [--status S] [--scope S] [--text T] | Finds decisions, and an overturned decision stays findable |
ropeshift decision show <id> | Shows one decision |
ropeshift decision record --statement S [--rationale R] [--scope S] [--category C]... [--citation C]... [--reversibility R] [--question Q] [--assumed] [--supersedes D] [--no-conflict D]... | Records a decision, or with --assumed a reversible assumption. The answer lists decisions with an overlapping scope. --supersedes replaces one, with no rework |
ropeshift decision overturn <id> --statement S [--rationale R] [--citation C]... | Reverses a decision in one transaction: rework for each completed work order, a notice for each lane, and the outcome on its experience record |
ropeshift policy list [--kind K] | Lists the versions of a policy, newest first. --kind is decision, the default, lane, delegation, autonomy, notify, or recovery |
ropeshift policy show <version> [--kind K] | Prints one version as its author wrote it |
ropeshift policy publish --file F | Publishes a new version of the policy its table names, [decision_policy], [lane_policy], [delegation_policy], [autonomy_policy], [notify_policy], or [recovery_policy], whose keys authorization describes, or [assistant], whose idle_stop and warm_idle_stop the API reference describes. A body names its version, and it must be newer than the one in force. Only a member can |
ropeshift agent list [--installation] | Lists the agent roster as the project resolves it: the built-in agents, then the installation's changes, then the project's, field by field. Each agent shows its kind, access, capability class, effort, approval, whether it is enabled, and the layers its fields come from, and the last line names where the routing guide comes from, the roster's digest, and the version of each layer. --installation lists the roster with no project's changes |
ropeshift agent show <name> [--installation] | Shows one agent: each field with the layer it comes from, the model it runs on each driver, from the driver profile's [agent.classes] unless the agent names a model for that driver, and its purpose, instructions, and report format |
ropeshift agent set <name> <field>=<value>... (--installation | --project P) | Changes an agent's fields at one scope, as a new roster version. The fields are purpose, kind, access, class, effort, approval, instructions, report, enabled, tools.allow and tools.deny (comma-separated categories: read, search, edit, shell, web, context, delegate), and models.<driver>. purpose, instructions, and report also take @<file>. A change names its scope with --installation or --project on the command line, never from ROPESHIFT_PROJECT or the directory, and exits 2 without one. Only a member can change the roster |
ropeshift agent add <name> [--from N | --file F] (--installation | --project P) | Adds an agent at one scope, copied from another agent or read from a TOML file that holds one [[agent]] table, with the keys of an agent definition. A name the roster already holds exits 4 |
ropeshift agent disable <name> (--installation | --project P), ropeshift agent enable <name> ... | Stops sessions from receiving an agent, or lets them again. An agent the default mapping or a work order that is not done names cannot be disabled: the command exits 4 and names what still uses it |
ropeshift agent reset <name> (--installation | --project P) | Removes a scope's changes to an agent, or removes an agent that scope added, as a new version. A scope that changed nothing of the agent exits 4, and so does removing an agent something still names |
ropeshift agent history [<name>] [--installation] | Reads a scope's roster versions, newest first, each with its summary, its author, its digest, and what it changed from the version before it. A name keeps the versions that changed that agent. It reads the project's layer unless --installation names the installation's |
ropeshift agent revert <version> (--installation | --project P) | Records an earlier version of a scope's layer as its newest version. A version that no longer fits the layers below it, or that would leave something without its agent, is refused |
ropeshift agent guide (show | set @<file> | reset) [--installation | --project P] | Reads the routing guide every coordinating session receives, sets a scope's own from a file, or removes it so the layer below holds again. set and reset name their scope as every change does |
ropeshift approval list [--state S] | Lists requests, each with what it asks and how it stands |
ropeshift approval show <id> | Shows one request: its call, the lane that asked or, for a plan approval, the plan and version, its digest, and how it stands. A request to approve an adopted plan also prints its groups as plan show does: what exists with its evidence, what continues, what is new, what is left out with each reason, and every file the adoption branch changed |
ropeshift approval approve <id> --digest D [--reason R] | Approves the one call a request names, and --digest says what you read. It also approves a plan version, the same as plan approve, a recovery request, which runs the act the orchestrator asked for as your decision, and a merge request, which approves the merge of a reviewed commit at person_approves or tries a held merge again; the digest of a merge request is the reviewed commit. An orchestrator can approve none of these. See authorization |
ropeshift approval deny <id> --digest D [--reason R] | Denies it. Denying a merge request sends the work to rework, with the reason |
ropeshift confirm <card> | Confirms a confirmation card a delegate prepared, with the digest it reads from the card, and prints confirmed <card>: <title>. The server binds the card's subject again first: a subject that changed since the card was prepared makes the card void, and the command exits 1 with stale_digest. Otherwise the card's exact call runs as you, through the same checks and events as your own call, and the card is used. A call the API refuses leaves the card failed: the command prints failed <card>: <title>: <refusal> and exits 1. A delegate's confirmation exits 8, and a request that is not a card exits 2 |
ropeshift decline <card> [--reason R] | Declines a card, which runs nothing, and prints declined <card>: <title> |
ropeshift effect list | Lists the effects a crash left unknown that nothing can observe, such as an input to a session or a profile's hook, each with its worker, lane, and how it stands |
ropeshift effect show <id> | Shows one |
ropeshift effect decide <id> --outcome O [--reason R] | Says what became of one, which only a member can. happened and not_happened settle it. retry lets a run perform it again, so it may happen twice, and an ended lane has nothing left to retry it. An effect is decided once, and a retry a crash cuts short asks again |
ropeshift notice list | Says how each notice stands on each channel: its kind, its attempts, and whether a channel took it. Delivery is at least once, so more than one attempt with a delivery is a notice its channel may have heard twice. See notifications |
ropeshift telemetry query [--signal S] [--name N] [--lane L] [--since D] [--limit N] | Reads the worker's local telemetry store, newest first: spans, data points, and the agent's log records, each with its attributes and the lane, work order, and generation its tags name. --signal is span, metric, or log, and --since takes a duration such as 1h. It prints 100 records unless --limit says otherwise. The local store keeps account attributes, which an export drops. See telemetry |
ropeshift telemetry lanes | Prints each lane's context at its last call, its tokens by type, and the cost its agent reported, which is a lower bound. Under a lane, an agent line gives the tokens each roster agent spent inside it, where the agent CLI reported which agent spent them. They are part of the lane's tokens, not added to them, and --json holds them in agents |
ropeshift measures [--window D] | Prints the product measures over a window, 7d by default, from the ledger alone: interruptions per completed work order beside the overturn rate, rework, and the autonomous decision rate, then the repeated-question rate, repeats prevented, work in progress, flow time, park time by trigger, cost per outcome by kind, and review agreement for the workspace and for each repository beside its merge authority, over the last 30 days and over all time. A rate with nothing under it says so. See measures |
ropeshift view <name> [--category C] | Prints one read model of the web UI, as JSON: needs-you, roadmap, plans, documents, decisions, questions, in-progress, on-hold, stuck, completed, shop-floor, operations, or search. --category narrows questions and decisions, and names one kind of record for search, such as work_order or decision. The search view lists every record of the project with its kind, ID, title, and state, which the web UI's command palette searches by ID and title. The documents view lists, for each plan, the planning documents its files recorded with every version and where each stands in review, and each requirement of its requirements documents with the criteria that serve it and their work orders. The roadmap view lists each plan's milestones in priority order with their progress, the layers of work that can run at the same time, the critical path, and the title, state, size, and milestone of each work order it places. The plans view gives each plan its milestones, each contract the ID its file gave it, which another contract's uses names, and the plan version whose approval waits, when one does |
ropeshift events [--after N] [--limit N] | Follows the ledger from a revision, one line for each event: what happened and to what, with none of a record's content. With --limit it stops after that many |
ropeshift audit [--installation] [--actor K] [--kind T] [--subject S] [--before N] [--limit N] | Reads the project's log, or the installation's with --installation, newest first: each event's revision, time, actor, type, and subject. --actor keeps one kind of actor, --kind the types that start with its text, and --subject one kind of record. A page holds 50 events unless --limit says otherwise, up to 200, and names the --before revision of the next. A filtered read looks at 5,000 events at most and says where to go on. With --json each event carries its whole record. The web UI's Audit reads the same |
ropeshift category list | Lists the workspace's categories: the built-in ones and those it added |
ropeshift category add <name> | Adds a category. A name is lowercase words joined by hyphens, and a category cannot be removed |
ropeshift search <words> [--kind K]... [--limit N] | Ranks candidates for a question among decisions, requirements, contracts, and open questions. A score orders one search and means nothing else: a person or an agent judges a match |
ropeshift document list | Lists the Markdown documents of every source, at the commit intake reads |
ropeshift document show <path> [--version V] [--instance I] | Prints one document. --version names an earlier version, and --instance names the repository when two hold the path |
ropeshift document versions <path> [--instance I] | Lists the versions of one document, newest first |
ropeshift document recorded <kind>:<id> [--version N] | Prints one version of a planning document, such as spec:checkout-api, as the ledger stored it when intake read the commit, which stays the same after the file changes. --version names an earlier version, and the newest is the default. With --json it also lists every version with its digest, the file and commit it came from, when intake recorded it, and whether a plan version a member approved covers it, an approval that waits lists it, or neither |
ropeshift lane start <work-order> [--lane L] [--profile F] | Asks the worker holding the claim to run a lane. It returns when the ledger holds the request, and a retry with the same lane ID is the same request. --profile names a TOML file that is this lane's own profile layer, over the built-in, user, and repository layers. It cannot raise the permission mode, change what the machine admits, or change push_on_stop |
ropeshift source list | Lists sources, their health, the files they cannot read, and each file whose base moved: a commit that never held the ledger's version and changes the file too is no new version, and merging the two is what settles it. A problem found at a plan's accepted commit names that version and the plan, and stays until a later commit fixes the file: one that holds the plan's version of it, or, for a file nobody could read, one intake takes the file from |
ropeshift lane attach <lane> | Puts your terminal on an interactive lane's pane, on this machine, so you see and type into the agent's session. On a headless lane, which has no pane, it prints the lane's stream, its newest 20 entries and then each new one as it arrives, and sends each line you type as a message to the lane; ending input leaves the lane running. It needs a terminal, tmux for a pane, and it refuses a lane that ended, a lane with no pane on this machine (a lane another worker holds, or one that has not opened its pane), and a parked lane. Detaching leaves the lane running: press C-b d, or C-b C-b d inside tmux, because the status line is off. When the lane's pane goes and the lane moves to a newer generation, as after a hand-off or a resume, the command attaches to the new pane. It waits as long as the lane stays parked, and it ends when you detach, when the lane ends, or when a lane that is not parked has no pane for a minute |
ropeshift lane list | Lists lanes. Each line states the lane's state, liveness, reachability, conditions, and whether the value is observed or last_reported |
ropeshift lane show <lane> | Shows one lane the same way, and a base line with the ref and the commit its branch began at. A lane that continues an in-flight branch has a continues line with that branch and the tip its own branch began at, and its base line names where that branch left the base, which its review diffs from. --json adds as_of, reported_by_epoch, base_ref, base_commit, continues_ref, continues_commit, and reads: the other repositories of the project the lane reads, each with its name, ref, and the commit its claim recorded, or the reason it could not be read |
ropeshift lane outline <lane> | Shows the plan a planning lane has committed to its branch, at the branch's tip now: the planning documents added or changed since the commit the branch began at, each with its path and kind, the milestones with their priorities, the contracts with their criterion and work order counts, the draft decisions, the work order's open questions with the blocking ones marked, and the request to approve the plan that stands for the tip. When none stands while a blocking question is open, it says the version is not submitted. It reads the repository on the machine the daemon runs on and only what the lane has committed. A branch it cannot read, because the lane runs on another machine or has no commit yet, prints one unread line with the reason. --json prints the whole outline |
ropeshift lane respawn <work-order> | Stops a running lane's session, and starts its next generation from that session. It needs a member's session |
ropeshift lane reset <work-order> | Lets the lane its breaker stopped start again, whether crashes stopped it or its generations reached the day's cap. A handoff, a resume, and a respawn count toward that cap, and a lane a handoff stopped goes on from that handoff. A lane the cap stopped reads day_capped, and only a member's reset starts it: an orchestrator's reset clears the crash window and leaves what the day counted |
ropeshift lane resume <work-order> | Gives a work order's parked lane a member's word, which wakes a lane that waits on a person. A lane parked on a usage limit or an expired sign-in waits on the worker's word and not on a member's, so this does not move it |
ropeshift repository add <path>... [--depth N] [--dry-run] | Registers repositories in the project from git clones on this machine, as a member. A path that is the top of a clone registers that clone, and any other directory registers the clones among its children, one level down, or N levels with --depth; nothing inside a clone or a hidden directory is searched. Each registration reads the remote and the default branch from git, names the repository, records the clone as this machine's worker's checkout of it, and is one event. A new repository takes the safe settings: review target branch, merge method merge, start from merged work, and merge authority person_merges. Naming a repository the project holds already records nothing new, and the worker keeps the checkout it had while that clone still holds the repository. A repository another project holds is refused, naming that project, and so is a path that holds no clone, with the reason; the others are still registered, and the command exits 4. --dry-run prints what would be registered and refused, and records nothing. Intake then reads each repository from this worker's checkout |
ropeshift repository list | Lists the project's repositories, each with its name, marked (removed) for one kept as history and (planning) for the planning repository a member named, its identity, the branch its lanes start from, how it merges, what dependent work starts from, where its work is reviewed, its merge authority, and its remote |
ropeshift repository show <name> | Shows one repository's record: its name, its state, active or removed, whether the project plans in it, by a member's choice or as its only repository, its remote and default branch, which the daemon reads from git, and its base branch, forge binding, merge method, review target, start, and merge authority, which a member sets. A forge line per worker that keeps a checkout of the repository says what that worker last found of its gh sign-in for it: ok, signed_out with what gh auth status said, or missing when the worker has no gh, and a repository that reviews through pull requests that no worker has reported on yet says so. It ends with the review agreement of that repository over the last 30 days and over all time: the decisions you made after a review, how often you agreed with it, the approvals you overturned, and the failures you overrode. The record is evidence for choosing a level, and it never changes one. <name> is the repository's name, its identity, or any unique prefix of the identity of seven characters or more |
ropeshift repository remove <name> | Takes a repository out of the project, as a member, once no open work order targets it; it exits 4 naming the work that still does. The record stays as history with state removed and keeps its name, which no other repository of the project can take. The repository leaves the repository index, so another project may register it, this machine's worker forgets its checkout, and intake no longer reads it. repository add in the same project registers it again with its settings |
ropeshift repository set <name>... [--name N] [--base B] [--merge-method merge|squash|rebase] [--start-from merged|accepted] [--review-target branch|pull_request] [--forge-binding HOST/OWNER/REPO] [--merge-authority person_merges|person_approves|review_approves] [--planning] | Changes the settings a member owns, and only a member can. Naming several repositories applies the same change to each, one event per repository, after every name has been found in the project; a change one of them refuses leaves the others changed and exits with that refusal. A flag left out keeps its value, and --base "" follows the default branch again. --name renames one repository, and a name another repository of the project holds exits 4. --planning makes one repository the project's planning repository and takes that from any other, in an event of its own, and --planning=false takes it back. --review-target is where completed work is reviewed and lands: branch, the default, reviews the lane's branch and pushes nothing, and pull_request has the worker push each change's branch and open a pull request on GitHub before its review, as onboarding describes. pull_request needs a forge binding, which ropeshift takes from a remote on a forge, such as [email protected]:acme/widgets.git, and which --forge-binding names otherwise; a remote that names no forge repository and no binding is refused with exit 2. The change stands whether or not a worker has gh, because the control plane cannot see a worker's gh when the setting changes, and it prints a warning to stderr when no worker has reported a working gh sign-in for the repository yet. --forge-binding "" takes the binding from the remote again. --merge-authority is how much of each change you decide after the review agent judged it: at person_merges, the default, finished work waits for you with the review's verdict per criterion, and you merge it; at person_approves, work whose every criterion passed waits in integrating for your approval of its merge, and ropeshift merges it; at review_approves, the review's pass approves the merge, and ropeshift merges once every check the base requires is green, and the audit says so. Each change is an event naming the record before and after. --start-from accepted is refused for a repository whose merge method is squash or rebase, and so is changing the merge method to either while it starts from accepted work, because those rewrite the commits the dependent work would be built on. A change that changes nothing records nothing |
ropeshift lane archive <lane> [--force] | Asks the worker that ran an ended lane to remove its worktree. Its branch stays. A lane with unpushed_work is refused, and --force removes it anyway, which only a member can do. The worker reads the worktree again first, and saves what it finds to a ref. Nothing is pushed unless the user's profile turns push_on_stop on, so until then a lane whose work no remote holds reads unpushed_work. See onboarding |
ropeshift message send <lane> --body B [--kind K] [--id I] [--reply-to R] [--generation G] | Records a message for a lane's current generation, or for one it names. --kind is instruction, notice, answer, or decision_notice, and a retry with the same --id sends it once. A message grants nothing: it never counts as a permission decision or as consent |
ropeshift message send --orchestrator <worker> --body B [--kind K] [--id I] | Records a message for the orchestrator of a worker that serves the project, which reaches it as one item of its next wake. Only a member sends one: with a delegate's credential it exits 8 with only a member does this. An orchestrator that is not running exits 4, and a worker that serves no repository of the project exits 2 |
ropeshift message show <id> | Says how far a message got: queued, at_worker, handed_off, admitted, replied, refused, or expired, with the reason and any reply. handed_off proves only a write, and admitted proves the session took it into a turn. Only a reply shows it was read. A message that has not entered a turn dies with its process, and reads expired with reason generation_ended, or ledger_fact when the next generation is told of it |
ropeshift message list <lane> | Lists what was sent to a lane, oldest first |
ropeshift orchestrator attach [--worker W] | Prints the stream of the orchestrator of a worker that serves the project, its newest 20 entries and then each new one as it arrives: the events it caused in the project, your messages to it with its replies, and the recovery requests it raised. Each line you type is a message to it, and ending input leaves, which stops nothing. --worker names the worker by name or ID, and is required when more than one worker serves the project. It needs a terminal, and prints no JSON |
ropeshift chat [--conversation ID | --new] [--name T] [--worker W] | Talks to your assistant in the project: it opens your newest conversation, the one --conversation names, or a new one, prints its newest 20 entries, then each new one as it arrives, and sends each line you type as a message. Ending input stops the session and exits 0, and the conversation stays. A start runs on --worker, or the conversation's last worker while it can, or the only worker that can; with several it exits 2 and names them, and with none it exits 4 and says why for each. It needs a terminal, and prints no JSON |
ropeshift chat list | Lists your conversations with the assistant, newest activity first, with each one's state, worker, and open cards, and each worker with whether it can run the assistant and why not |
ropeshift chat show <id> [--limit N] | Prints a conversation's newest entries, oldest first: your messages with their delivery state, the assistant's replies, what it ran, the cards it prepared as they stand now, and markers where its session started, stopped, compacted, or cleared |
ropeshift chat new [--name T] [--worker W] | Starts a new conversation, which stops your running one first and says so |
ropeshift chat open <id> [--worker W] | Starts a conversation's session, resuming what it had, which stops your running one first, and sends nothing. A session no message reaches stops after the assistant policy's warm_idle_stop, 2 minutes by default |
ropeshift chat rename <id> <name> | Names a conversation, 1 to 80 characters |
ropeshift chat delete <id> | Stops a conversation and removes it with every message it holds, on the control plane and on each worker that ran it. Its actions and the cards it prepared stay in the audit. The agent CLI's own record of a session, where the CLI keeps one, is outside ropeshift's control |
ropeshift chat stop <id> | Stops a conversation's session. The conversation stays, and resumes when you send |
ropeshift chat compact <id> | Asks a running conversation's session to compact its context. A conversation whose session is not running exits 4 |
ropeshift chat clear <id> | Starts a running conversation's next generation with an empty context, in the same conversation. Earlier entries stay readable, marked as before the clear. A conversation whose session is not running exits 4 |
ropeshift chat send <id> --body B [--worker W] [--id I] | Sends the assistant a message, which opens a stopped conversation first and reaches its session once it runs. A message grants nothing: a card waits for your confirmation whatever a message says |
ropeshift chat targets | Lists what you can talk to in the project: your assistant with your newest conversation, the orchestrator of each worker that serves the project, the planning sessions, and the other lanes that have not ended |
ropeshift fleet show | Shows the fleet's mode and the caps a claim is held to |
ropeshift fleet run, pause, drain | Sets the mode for the whole fleet. pause takes no new claims and starts no new lanes, and a running lane that crashes still restarts. drain also stops new generations. Each lane already running goes on |
ropeshift fleet caps [--wip N] [--per-repository N] [--per-worker N] | Sets what a claim is held to. A flag left out keeps its value, and 0 means no limit. A claim already granted stays |
ropeshift login | Asks for the passphrase on the terminal and prints a session for eval. It lasts an hour |
ropeshift sign-out | Ends the session this shell holds, so its token opens nothing again. The token in ROPESHIFT_MEMBER_TOKEN is all it needs, so it works with no terminal, and it never asks for the passphrase. With no token, or one whose session expired or already ended, it says there is no session to end and exits 8 |
ropeshift sign-out --all | Ends every session of yours, on every client, and revokes every delegate credential of yours that still acts, in one step with one event, and prints how many of each. With no session it asks for the passphrase on the terminal |
ropeshift delegate create --project P --label L --expires D | Makes a delegate credential for an agent outside ropeshift, bound to the active project P. L is 1 to 64 characters and never assistant, which only the assistant's own credentials carry, and D is from one minute to thirty days, as a duration such as 8h or a number of days such as 7d. It prints the credential once, then This credential is shown once. Store it now; ropeshift keeps only its digest., then the line export ROPESHIFT_DELEGATE_TOKEN=<token> for the agent's shell. --json prints the credential with its token |
ropeshift delegate list | Lists your delegate credentials, oldest first: ID, state (active, expired, or revoked), project, label, expiry, and last use, or never used |
ropeshift delegate revoke <id> | Ends a credential for good. Its next call is refused with bad_delegate |
ropeshift delegate remove <id> | Deletes the record of a credential that no longer acts. An active credential exits 4: revoke it first. The audit then names the delegate by the credential's ID |
ropeshift operation list | Lists each changing operation of the API: its ID, its class (operational, consent, or member_only), whether the delegate policy may exempt it, and its label. --json adds the reason an operation is never exempt |
ropeshift member list | Lists each member that holds a live session, with when each session began and when it ends, and how many members can sign in. A session's token is never shown, because the ledger keeps only its digest |
ropeshift passphrase set | Sets the passphrase on the terminal. The first needs no session, and a later one asks for the current passphrase. A passphrase has at least 8 bytes |
ropeshift init | Sets up this machine for solo mode, and a second run says only what is left. It asks for the first passphrase on the terminal and keeps one already set. It waits for the worker's registration, and with no daemon running it runs one for its own length, because a first start registers the worker. It runs the doctor and says, for each agent CLI, whether to install it, sign in through its vendor's own flow, or nothing, with the level the worker starts at. It writes a sample contract to the installation's directory and keeps one already there. It exits 1 when no agent CLI is usable, after every other step. See onboarding |
ropeshift backup <file> [--installation] | Copies the project's ledger to a new file through SQLite's online backup, while the daemon goes on writing. The copy holds every record of that project and nothing of another project, and project import registers it in another installation with its ID. --installation copies the installation database instead: the registry of projects, the member and the passphrase's hash, the member sessions, and the workers, and it takes no project. Restoring a whole installation takes its installation backup and each project's backup. A relative path is read from where the command runs, a file already at the path is never replaced and exits 2, and only the owner can read the copy. It needs a member's session, because the copy holds every record it names. A control plane with no online backup exits 1 |
ropeshift service install [--name N] [-- daemon flags] | Runs the daemon as a launchd agent on macOS or a systemd user unit on Linux, from the ropeshiftd beside this command, and starts it, or restarts it with the new definition. The flags after -- go to ropeshiftd solo as they are. A flag it refuses, or a --source that is not an absolute path, exits 2 before anything is written. The definition keeps this shell's PATH, locale, and ropeshift's own location variables, because a service manager starts the daemon with almost none, and it holds no other variable. The launchd agent sets ProcessType to Interactive. The name is dev.ropeshift.ropeshiftd on macOS and ropeshiftd on Linux by default. See onboarding |
ropeshift service uninstall [--name N] | Stops the service and removes its definition. No lane stops: a lane's processes live outside the service, and the daemon adopts them when it starts again. A service that is not installed exits 3 |
ropeshift worker doctor | Reports each agent CLI on this machine: whether it is present, its version, whether that version is qualified, and the kind of its sign-in. It uses the vendor's status command, reads no credential, and needs no daemon. It exits 1 when no CLI is usable |
ropeshift worker list | Lists registered workers, each with its epoch and protocol, and what it last measured of its machine: CPU use, load, memory used of the total and available, memory pressure, free space on each watched volume, the per-worker cap in force beside the recommendation, any warning past a threshold, and how long ago it measured. A measure the machine cannot provide reads unavailable, and a worker that never reported says so |
ropeshift orchestrator show <worker> | Shows a worker's orchestrator: what a member asked of it, and how it reads |
ropeshift orchestrator start <worker> | Asks for its orchestrator, resets a breaker that stopped it, or replaces a session that stalled. view stuck and needs-you list one that tripped or stalled. No agent can ask for one, and no session starts until there is something to judge |
ropeshift orchestrator stop <worker> | Stops its orchestrator, which stops no lane |
ropeshift worker token | Makes a join token for one worker. It is shown once |
ropeshift worker autonomy <id> | Shows a worker's sign-in, the level that holds, any run window, and whether its orchestrator can claim now |
ropeshift worker level <id> manual|attended|unattended | Chooses a worker's level. unattended on a subscription is refused until a member acknowledges the stated risk for that worker |
ropeshift worker caps <id> [--max-lanes N|none|recommended] [--per-sign-in N|none] | Shows a worker's lane caps beside the cap in force and the recommendation it last reported, with the numbers behind it, and with a flag sets them in the user's profile of that worker's machine. Any positive number stands, with no upper bound; none caps nothing, and recommended follows the recommendation. A flag left out keeps its value. A per-worker cap above the recommendation is saved, and a warning on stderr names the recommendation and why. The worker reads the change at its next start and its next measure, with no restart. A worker on another machine is refused: its caps are in the user's profile on that machine |
ropeshift worker risk | Prints the statement a member acknowledges, and its digest |
ropeshift worker acknowledge-risk <id> --digest D | Records that a member read the statement that digest names, for one worker, as an event. It changes no level, and a changed statement asks again |
ropeshift worker window-open <id> [--for D] [--id I] | Opens a run window, inside which an attended worker's orchestrator claims. It lasts 4 hours by default and 12 at most, and closes by itself. A worker holds one at a time |
ropeshift worker window-close <id> | Ends a run window. No lane stops, and work claimed but not started waits for the next window or a member |
ropeshift mcp lists 9 tools for a lane and 18 for an orchestrator, by the token it runs with. lane_stop ends a stuck session and starts the lane's next generation, because canceling work is a member's. The orchestrator's lane_restart, lane_reset, work_retry, and work_replan recover stuck work within [recovery_policy], and a call outside it raises a request a member decides. See authorization.
These commands are for ropeshift or an agent CLI to run, and a person does not need them:
| Command | Does |
|---|---|
ropeshift hook <event> | Reports one hook event to the worker, and spools it if the worker is down. It always exits 0 |
ropeshift mcp | Serves a lane's tools over stdio, and reaches only the local worker. It takes no arguments, and an argument exits 2 before it serves |
ropeshift lane-shim | Holds a headless session's pipes in a process of its own, so the session outlives its worker. It journals every line, serves that journal on a private socket, and writes each input at most once |
ropeshift lane-pane <file> | Replaces itself with an interactive session in its pane, with the exact environment a private file holds, and removes that file first |
ropeshift statusline [--pass] | Reports one status line input to the worker. It is the driver's half of an interactive lane's status line, and --pass prints the input for a person's own command after it in a pipe |
The daemon#
ropeshiftd solo runs the control plane and this machine's worker in one process. ropeshift service install -- <flags> passes the same flags to it under the service manager. ropeshiftd help lists the daemon's commands, and ropeshiftd solo --help prints these flags with their defaults.
| Flag | Default | Meaning |
|---|---|---|
--source <path> | None | A repository to read work and documents from, into the installation's first project. Repeat it for each repository. A repository another project holds is refused: each read says which project holds it, and reads nothing from it. Intake also reads, in each project, every repository repository add registered there from this machine |
--ref <ref> | The default branch | The ref intake reads in each source |
--dir <dir> | The whole repository | The directory intake reads in each source |
--web <address> | 127.0.0.1:7317, or ROPESHIFT_WEB | The loopback address of the web UI, or off |
--telemetry <address> | 127.0.0.1:7318, or ROPESHIFT_TELEMETRY | The loopback address of the telemetry receiver, or off. See telemetry |
--intake-tick <duration> | 30s | How often sources are read |
--notify-tick <duration> | 30s | How often members are told what waits. See notifications |
--forge-tick <duration> | 1m | How often the worker reads gh's sign-in for each repository that reviews through pull requests, and each pull request it watches, and how long a failed push or pull request waits before its next attempt. See onboarding |
--telemetry-tick <duration> | 5s | How often the ledger is read into spans and metrics |
--delivery-tick <duration> | 30s | How often each project's timelines and delivery records are folded from what its log added. See delivery records |
--lease-tick, --batch-tick, --wake-tick | 5s, 5s, 1s | How often lapsed leases end, closed question batches reach members, and due wakes fire |
--lease-ttl, --heartbeat | 60s, 15s | How long a lease lasts, and how often the worker beats |
An installation keeps its ledger, installation database, journal, and telemetry store in its state directory, and its sockets in its run directory. The ledger, ledger.db, holds the default project's records. The installation database, installation.db, holds the registry of projects, the member and the passphrase's hash, the member sessions, the workers with their autonomy and run windows, and the orchestrators. A daemon started on an installation with only a ledger moves those records into a new installation database and keeps the ledger file where it is:
| Directory | macOS | Linux | Moved by |
|---|---|---|---|
| State | ~/Library/Application Support/ropeshift | $XDG_STATE_HOME/ropeshift, or ~/.local/state/ropeshift | ROPESHIFT_STATE_DIR |
| Run | ~/.ropeshift/run | $XDG_RUNTIME_DIR/ropeshift, or ~/.ropeshift/run | ROPESHIFT_RUN_DIR |
A second installation on one machine sets both variables and its own --web and --telemetry addresses.
Exit codes#
| Code | Meaning | What to do |
|---|---|---|
| 0 | The command did what it said | Nothing |
| 1 | The control plane could not answer, or the command failed for another reason | Retry, and read the message |
| 2 | The command line or the request is invalid | Fix the command |
| 3 | The record does not exist | Check the ID |
| 4 | The ledger's state refused this: a claim was lost, work was not lapsed, the move has no edge, or a removal would lose work no remote holds | Read the current state |
| 5 | The fence is stale: another holder owns this work | Stop, and read the current fence in the message |
| 6 | The lease lapsed and this holder can return | Return, then retry |
| 7 | The review is recorded, and the definition of ready names what still holds the work back | Resolve what it names. The work order moves on its own |
| 8 | This actor may not take this step, or the step needs a member's session and has none | Use an actor that may, or sign in on a terminal |
| 9 | Nothing answered on the socket | Start the daemon, or check --socket |
| 10 | The command's operation became a confirmation card, which runs only when a member confirms it | Ask a member to confirm the card in Needs you or with ropeshift confirm |
Written for ropeshift v0.1.0-alpha.14. The source is docs/cli.md at v0.1.0-alpha.14 (opens in a new tab).