Skip to content

Latest commit

 

History

History
1265 lines (1126 loc) · 102 KB

cli-selection.mdx

File metadata and controls

1265 lines (1126 loc) · 102 KB
title CLI spaces
description Space preparation, registration, target selection, discovery, and infrastructure diagnostics.
kind Reference
audience operators

space manages this machine's space records. cotal use <space> selects the target in every folder until another use or use --clear. Explicit --space, --server and --creds keep their own target rules. A selection Cotal adopts automatically does not override another project's running space. status reads infrastructure and local records without starting or repairing components. An explicit empty or whitespace-only name on use, space show or space forget refuses with USAGE_INVALID, exit 1, before connector seeding or registry lookups.

space [#selecting-a-space]

cotal space [--json|--plain]
cotal space show [<name>] [--json|--plain]
cotal space add <name> --server <url> [--root <dir>] [--mode auth|open] [--tls] [--allow-unencrypted-overlay] [--force] [-y|--yes]
cotal space add [<name>] (-f|--file <bundle.json> | --from <https url>) [--root <dir>] [--server <url>] [--force] [-y|--yes]
cotal space create <name> [--root <dir>] [--adopt]
cotal space forget <name>
cotal space export <name> --out <private-file> [--json|--plain]
cotal space delete <name> [--dry-run] [-y|--yes] [--json|--plain]
cotal use [<space> | --clear] [--json|--plain]

Space inventory

space lists the spaces this machine can reach: each one's broker state, server, mode, origin (started here, registered or discovered) and root, with the selected one marked. Inside a project whose root has one running registered space other than the automatically adopted selection, that space is marked as this folder's, since a command without --space targets it there. It probes each broker that this machine started or that was registered by hand, and reports one that does not answer as unreachable when the connection fails, or not answering when it times out. A stopped local listener is reported as broker process is stopped. Its registration stays. Since 0.167.1, when this folder is already a space root, the listing's create step uses cotal space create <name> --root <dir> to prepare another space in another folder. An unoccupied folder still offers cotal space create <name> for this folder. A discovered space is never dialed by a listing and reads not checked. space show [<name>] shows one space in full and probes only that broker. With no name it is about this folder: the space it has registered, else the one it holds prepared or stopped, else the selected one. This does not change what other commands target. If cotal use explicitly selected a different space, space show says that commands such as cotal who still target the selection here. Pass --space <name> or run cotal use --clear to target the folder's space instead. Neither space nor space show writes anything. A registry record that cannot be read refuses both with SCHEMA_INVALID, exit 1, naming its file.

--json writes one document. space gives current (the selected space or null), currentRecorded, folder (this folder's space when it is marked, else null), items and prepared; each item is the row cotal status --json gives under meshes.items: space, server, mode, root, origin, tlsRequired, eventsRequired, modeChecked, current, check (reachable, unreachable, slow-link, broker-stopped or not-checked) and catalog. slow-link is the not answering state used by status and connection refusals such as send. space show adds recordedAt, attachHost, maxSessions, storeDir, unencryptedOverlay, the login pins of a user-auth space under userAuth and the catalog's id, slug, kind and role. It leaves credential paths out. space show also gives rootGone: true when this machine's saved stack definition names that root but its stack journal and broker configuration are no longer there. The root row then says the folder was moved or deleted, even if the broker is reachable or has recreated empty directories at the old path. Its next step stops the stack with cotal down --space <space> --yes from any folder. See the missing-folder stop. A name that is not registered is refused with TARGET_NOT_FOUND, exit 2, and so is a bare space show outside a project with nothing selected. Each entry under prepared has space, root, preparedAt, current, rootMissing, which is true when its project folder no longer exists, state and lastOperation. state is prepared for a space that never started, stopped for one whose stack ran and was stopped, and unsettled when its last up or down recorded no outcome. lastOperation names that operation and how it ended, such as `cotal down`, completed, or is null. space show of a prepared space gives those with the kind prepared-space. The listing marks a missing folder (no longer exists) and names cotal space forget <space> for it instead of cotal up. If you stop a stack and rename its project, run space show <name> in the renamed folder. It reads the matching journal and tells you how to move the folder back. After a completed cotal down, it also gives the exact cotal space forget <name> and cotal space create <name> --adopt --root <dir> commands for keeping the new location.

space add registers a space that runs elsewhere, so --space and use can reach it. A name space create refuses, such as one that starts with - or holds a *, given or named by a bundle, refuses with USAGE_INVALID, exit 1, before anything is written. With --server, the trust comes from --root's .cotal/auth, and the mode is auth when that folder holds the space's trust, open otherwise. --root defaults to this project. Outside one it is required, and leaving it out is a one-line USAGE_INVALID refusal whose remedy says what to pass: an open space keeps no credentials there, so any folder will do. With --file, a user-auth connection bundle exported where the space runs supplies the login pins and the server, unless --server names another address for that broker; --from fetches the space's discovery document instead, after you agree to the fetch, and needs a terminal. Before anything is written, space add checks that the address may carry credentials, that the trust composes, that the broker enforces the mode, and that the credentials open the space; a user-auth space's exchange must answer as the issuer it pins. An open broker answers for any name, so an open space must also be one the broker serves, as its streams show. A name it does not serve is refused with TARGET_NOT_FOUND, exit 2, naming the spaces it does serve. On a terminal it then shows what it will trust and asks; --yes skips that question, but not the confirmation of fetched pins. It never changes the selection.

A refusal writes nothing and carries its code: USAGE_INVALID or SCHEMA_INVALID (exit 1) for input, and CONFLICT, TARGET_UNAVAILABLE, TARGET_NOT_FOUND, DEPENDENCY_UNAVAILABLE, UNSUPPORTED, AUTH_REQUIRED or PERMISSION_DENIED (exit 2) for what the checks found. A name that is already registered is a CONFLICT, and its remedy offers --force only for a registration added by hand. A broker that does not answer is a TARGET_UNAVAILABLE, and its remedy offers --force. A broker that requires auth, with a --root that holds another space's trust, is a DEPENDENCY_UNAVAILABLE that names the space the folder holds. When no broker answers at --server, or at a bundle's server, the TARGET_UNAVAILABLE refusal says whether its host name resolves and whether anything took a connection at its port. When a broker answers there under another scheme, such as nats:// for a tls:// address, the remedy names that address, and says when it has no TLS. A port that takes no connection gets the port check as its remedy. For --server, the --force route follows either one. --force replaces a registration added by hand, never one this machine started or a catalog lists, and adds a --server space without checking its broker, which suits a space that is down right now; a user-auth space is always checked. Such a registration records that its mode was not checked: space and space show show the mode as not checked, with modeChecked: false in --json, and whoami does not state what that mode implies as fact. Declining the question is a no-op with a USER_CANCELLED warning. --json gives the registration under space, in the shape space show gives, with verified and replaced.

Connection bundle export

space export <name> --out <private-file> copies a registered remote user-auth space's connection bundle. It preserves the recorded server, TLS requirement, IdP and exchange pins, provisioning and Manager-authority URLs, and required-events policy. The existing sentinel credential comes from that space's private custody directory, including when a discovered space's project root is bound elsewhere. It must parse as a user credential whose declared permissions deny all publish and subscribe subjects and carry no response grant. These local checks do not verify its issuer signature or current broker admission. Local paths and catalog account metadata are omitted.

The output passes the same bundle validator as space add --file. Export reads local state; it does not refresh a catalog, contact a broker, issue a credential or verify current access. The receiving user still needs their own sign-in and current space grant. Legacy custody that needs migration refuses without moving it. Open, static-auth and locally hosted registrations refuse this command. It never substitutes an account signer.

The output parent must already exist and pass the protected-directory checks. Managed .cotal and workstation state are forbidden destinations. Publication creates a private file and refuses every existing path, including a symlink; there is no overwrite flag. Unconfirmed publication is reported as unknown and is not retried. Reports name the space and output path, never the bundle, sentinel, login token or signing material. Keep the exported file private.

Local preparation

space create <name> prepares a space to start on this machine. It records the name and the root, which is --root or this folder, and makes <root>/.cotal/; cotal up in that root then starts the space under that name and drops the prepared record. It also writes the default persona into <root>/.cotal/agents when the root has none, as setup does, and leaves one you edited as it is. --json lists the files it wrote under result.written. The project and its ancestors must be physical directories owned by you or root, with no symlinks. World write refuses. A Linux directory can be group-writable if an ancestor owned by you or root gives group and other accounts no search permission. Otherwise, group write is allowed only on a directory you own whose group is your user private group, the Debian and Ubuntu default, and that has no extended ACL. For the private-group check, getent must show that the group is your primary group, lists no other member and is no other account's primary group, and getfacl must show no ACL entries beyond the base ones. When getfacl is not installed, python3 -I reads the entry's extended attribute names without following symlinks instead. Either system.posix_acl_access or system.posix_acl_default means an extended ACL and refuses; unrelated attributes do not. That account list counts only when /etc/nsswitch.conf names files and systemd alone for passwd and group. A directory source such as LDAP or SSSD can list part of its accounts, so with one configured, the private-group check refuses. getent, getfacl and python3 run from your PATH with a 2 second limit and a 4 MiB output limit each, so the first check in a process can take a few seconds. A proven group holds for the life of the process. When neither ACL reader is installed, or the selected read fails, the private-group check refuses. Install the acl package for getfacl, or remove group write. Root-owned sticky temporary directories are allowed. New control directories, the persona catalog .cotal/agents included, use mode 0700, even with a group-writable umask. An unsafe existing path refuses before the prepared record is written, without changing its permissions. The refusal names every unsafe path in the chain at once, the reason and one remedy such as chmod g-w <paths> that lists each path. A path that its group and every account can write gets chmod go-w, since chmod o-w alone would leave the group write that refuses next, and the other group and world gaps join that one command. When a symlink is the gap, the remedy names the physical path the folder resolves to. It starts nothing and leaves the selection as it is. cotal up applies the same rule to the root it starts in, before it writes anything, so it never starts a stack that down would refuse to stop from that root. cotal up starts a space only under a name of 1 to 64 letters, digits, underscores or hyphens that starts with a letter, digit or underscore, because a name that starts with - cannot be passed as a flag value. space create refuses any other name, such as café or -x, with USAGE_INVALID, exit 1, before anything is written, with a remedy that says which characters a name can use, and cotal up refuses a --space that starts with - the same way. The limit is 64 because each local file that carries a space spells its name twice over, and a file name holds at most 255 bytes. cotal up refuses a longer name that an earlier release prepared the same way, before it starts anything, and names cotal space forget and a shorter name. space add and meshes add refuse a longer name with USAGE_INVALID, exit 1, and write no record, because a space added from elsewhere is carried by the same files. If saving a prepared-space record fails, Cotal attempts to remove its temporary sibling and reports the original error without publishing a partial record. It refuses with CONFLICT a name that is registered or prepared, a folder that is already a space's root, and the home folder, whose .cotal holds this machine's own records. It refuses a folder that is, or is in, a control directory, which is a project's .cotal or the Cotal home, judged by the path given and by the path its links lead to, with CONFLICT and nothing written. A home COTAL_HOME redirects may hold project folders beside its records, so under it only the home itself and its record entries (daemon, meshes, prepared, services and the like) are control paths. The next step names the project folder that .cotal belongs to. A project folder inside another project, outside its .cotal, is a project of its own. For a folder another space uses, the next step names creating it in another folder with --root <dir>, and starting, selecting or forgetting the space that uses the folder. A folder this account cannot write, such as /, refuses PERMISSION_DENIED, exit 2, with nothing written, and so does a Cotal home (~/.cotal or COTAL_HOME) it cannot write. A .cotal that links to a folder that does not exist refuses TARGET_NOT_FOUND, exit 2, naming the link and its target. A folder whose path contains a control character, such as a tab, a newline or an escape character, or a bidirectional formatting mark, which can show one path as another, refuses USAGE_INVALID, exit 1, with nothing written, in space create and in cotal up. The refusal names the character and shows the path with it escaped. space lists prepared spaces under their own heading, below a line that says no space has been started or registered yet when that is so, and space show, use and whoami accept one. Once one of them has run, the heading gets a State column, and the line says no space is running or registered. A space whose stack ran and was stopped reads as stopped in space, space show and use, with its last operation, as status reads it. A command that targets a prepared space refuses with TARGET_UNAVAILABLE, exit 2, naming the root to start it in, and so does cotal up --space <name> run from another folder. Its Next names cotal up --root <root> --space <name>, which starts it in that root from where you are, and cotal space forget <name>, which lets you start it in the current folder. When that root's last up or down was cut off before it recorded an outcome, as an up interrupted before it registered the space leaves it, the refusal says so and names cotal status in that root, which names the step that finishes or settles it. cotal up --space <name> in a folder that is already another space's root refuses with CONFLICT, exit 2. space add refuses a prepared name. A prepared space records its folder by path, and moving the folder leaves nothing in it that names the space. A bare cotal up in a folder that names no space, while the selected space is prepared in a folder that no longer exists, refuses TARGET_UNAVAILABLE, exit 2, rather than start a space named after the folder there. Forget the space with cotal space forget <name>, prepare it again in its new folder with cotal space create <name>, then run cotal up. Until then, space create of that name says its recorded folder no longer exists.

Forgetting a local record

When a broker registered by hand does not answer, commands such as send and the delivery daemon name cotal space forget <name> as the way to unregister it. The refusal keeps the registration and does not start a local replacement. Start the broker where it runs to keep using that space. For a discovered space, the next step names removal from the provider's catalog followed by cotal sync, because space forget cannot remove a catalog-owned registration.

space forget <name> removes a registration this machine keeps. It stops nothing, deletes nothing on the broker, and keeps the files under its root. It refuses a space this machine is running with LIFECYCLE_BLOCKED, because cotal down stops it, and a discovered space with CONFLICT, because its catalog keeps it. A stack cotal up started stays a prepared space at its root after that down, so the refusal names cotal down and then space forget again. A legacy root's down drops the record, and the refusal says so, unless the space is named after its folder: that down keeps the record, and the refusal names space forget again. A space whose root holds its stack journal counts as running while any stack member's process may still run. The refusal names one such member and writes nothing: the registration, the selection and the root's files stay. A space whose folder was deleted while it ran also refuses with LIFECYCLE_BLOCKED and keeps its record. A controller stack whose instance records show a member still running names cotal down --space <space> --yes. Any other such space refuses while something still listens at its recorded broker address that no other registration names, and names the process listening there to stop. A member whose process is gone without its stop receipt does not block, and the result warns with STACK_MEMBER_UNSETTLED that it was never stopped cleanly. A prepared space is forgotten the same way, and the .cotal/ that space create made stays. A prepared record that cannot be read names no folder, so forgetting its space removes only that file, and the result's root is null. A damaged registration is removed with any prepared record of the same name in one forget. The prepared root still names stopped stack definitions to release, and recorded running stack members still block the forget before anything is removed. This also covers an unreadable pre-hex registration whose filename names the space unambiguously. meshes rm --force names space forget for such a record rather than skipping its stack checks. Forgetting the selected space clears the selection. Forget also removes the per-space preferences saved under that name, so a later space with the same name starts without them, and the receipt lists each removed key and value so you can set them again. If that removal fails after the record is gone, the run is partial and names the config unset to finish it, after the chmod when the preferences folder is one another account could write. Forget also removes the chat sessions the terminal app remembered for the space, with the direct messages it recorded as read there, and the receipt counts the sessions as removedChatSessions. If that removal fails, the run is partial too. Forget also removes the stack definitions cotal up saved for the space at its root, with their stopped instance records, so another folder can start a stack under the same name. The result lists them. The root's stack journal stays, keeping the stack's mode, address and store, and no longer names the instances forget removed. After space create in that folder, the space reads as prepared but not started, and up --no-manager and down there start and stop only the new members. A journal an earlier release left naming removed instances is not changed, and down there still refuses TARGET_NOT_FOUND. While a member was not stopped cleanly, or the root holds preserved state, they stay and the result warns with STACK_DEFINITIONS_KEPT. For a member that was not stopped cleanly, the warning names cotal down --yes in the root and then space forget again. When the stack's folder is gone, it names cotal down --space <space> --yes, which stops the stack and removes them. Forget keeps the other services saved under the name, such as one cotal service add saved, with their instance records. The result names them as keptServices, and a later space with the same name inherits them: its cotal service lists them and its up names them. A later space in another folder does not start one, as Running a service describes. cotal service remove <name> --space <space> --yes in that space forgets one. While no space has the name, cotal service finds no space for it, so remove a service before you forget its space to drop it at once. status in a forgotten space's root then selects no space and probes no broker. When nothing left in that root's .cotal/ names a space, its next step is cotal space create <name> --root <root>, because a bare cotal up there would start a space named after that folder. A command run there that finds no broker at the default address says that no space is registered or prepared for the folder and names the same step. That refusal has no Mesh: line, and its target names only the folder, because no space was resolved there.

In open or static-auth mode, an unanswered --server address that differs from the registration retained by target resolution gives TARGET_UNAVAILABLE, naming the address that did not answer. Its Next names the recorded broker and says to drop --server to reach it. If resolution retained no registration, the Next says to check the address instead. For a prepared space and an explicit nats://127.0.0.1:<port> address, it also gives cotal up --root <root> --space <space> --server <url> to start that project there. The request is not sent to the recorded broker in its place. A trailing slash or scheme case change in --server retains the registered space, including when its broker does not answer. The refusal gives the same next step as --space for that registration, including where to restart a stopped local space. Matching preserves the URL's transport scheme and TLS intent. If equivalent addresses name several registered spaces, pass --space to choose one. When an overriding --server requires auth but the selected space is recorded as open at another address, the refusal names both brokers. Its Next says to check the address or drop --server to reach the space at its recorded broker, not to start a new space in the current folder. Target resolution with --server does not sweep recorded brokers for liveness. The command checks only the broker it was given. status --all still checks every recorded address because --all asks for that scope. This refusal wording does not describe the infrastructure report from status.

Live deletion preview

space delete <name> --dry-run reads the registered broker in open or static-auth mode. It requires the broker's mode to match the registration, and a static connection must confirm its current account and user identity. It reports the known first-party streams and bucket backing streams as present or absent, the broker-observed transfer-stream targets under a second exact-name grant in static mode, and the entries in the presence bucket. A presence name that is missing or only whitespace is shown as that participant's id. Both static connections must confirm their own identity and the same broker server ID. A failed or incomplete native read refuses instead of showing missing resources as absent. The snapshot is non-atomic and presence is not an authoritative liveness or membership check. User-auth deletion inventory and apply are not supported. The dry-run removes no live or local state, and a read that covers its whole scope exits 0. A space that is prepared and not running, including one stopped with cotal down, has no live broker to read or delete from: space delete refuses it with TARGET_UNAVAILABLE, exit 2. For a stopped stack it names cotal reset store <space> --yes, which removes the stored streams, and space forget, which removes only its local record. For a space that never ran it names only space forget, because no streams were stored.

The dry run also reads the space's workflow runs from its records bucket and lists each run that has not finished, with its recorded state. Deleting the streams removes those runs, and a run still waiting for an answer cannot be answered or resumed afterwards. To read a run's open request first, run cotal up, then cotal run show <run>. The typed confirmation says how many unfinished runs go with the space, and the receipt lists the runs it removed.

On a space this machine started, the apply refuses LIFECYCLE_BLOCKED while the space's own stack still runs here, before any broker connection. On a controller root that is any service instance of the space other than its broker, and on a legacy root any recorded daemon other than the broker. Deleting the streams under them leaves a stack that can neither start nor stop. The refusal names the running services and cotal down, then cotal reset store <space> --yes on a controller root or cotal clean store --force on a legacy one to remove the stored streams. When a service that is not one of the stack's members runs, such as one added with cotal service add, cotal down refuses too, so the refusal first names cotal service stop <name> --instance <id> --space <space> --yes for each one. With only the broker left after that, it names the delete again in place of cotal down. The dry-run opens with a verdict, as reset store's does: the apply would refuse, with that refusal's reason and remedy, or it is offered, with cotal space delete <space> --yes as Next. --json carries the refusal as applyBlockedBy and as a LIFECYCLE_BLOCKED warning.

Live deletion

Bare space delete <name> displays that impact on an interactive terminal and requires typing the exact space name. Its question, and the message under a wrong answer, wrap to the terminal with each continuation line under the prompt's bar. A script supplies the exact positional name with --yes; --json without --yes refuses before a connection. After confirmation the command reads the broker again and refuses if the stream states, transfer names, presence identities, registration, trust or broker identity changed. After a typed confirmation it also refuses CONFLICT, exit 2, when a stream's message count differs from the impact it showed, as when a message is posted while the confirmation waits; the refusal names each changed count and deletes nothing. It opens a separately minted exact-target connection, checks each stream state again before the first delete, and submits one deletion at a time. A native acknowledgement is reported as deleted; prior absence is separate, and the receipt lists only the groups that have a name. It then checks each target's stream info and enumerates transfer names again. A surviving or newly observed resource produces a partial outcome if deletions were acknowledged; an incomplete post-read stays unknown. A refused or unconfirmed delete stops the sequence without retry, reporting acknowledged names and refused, unknown or remaining targets. This is not atomic: a live process can recreate a stream after the final read. The result does not claim that processes stopped, or remove registrations, credentials or local files. Open-mode impact and receipt label that any broker client can delete the space. space forget is not a substitute for live deletion.

Ctrl-C or SIGTERM during the apply reports what the command left and exits 130 or 143; with --json the report is the envelope on stdout. Before any delete was submitted the outcome is failed and the streams are as they were. Once a delete was acknowledged it is partial, listing the acknowledged streams and any delete still unconfirmed, with cotal space delete <name> --dry-run to see what remains. After every delete was acknowledged and before the check that nothing remains, it is unknown.

The receipt's Next names the route back. On a space this machine started, the broker keeps running without the streams. Until they are created again, cotal history, cotal send and cotal run refuse TARGET_UNAVAILABLE, exit 2, on an auth or user space and on an open space this machine started: the streams are not on the broker, and the remedy names cotal up in the space's root. cotal status shows Space streams: not on the broker and puts the same step first in its Next. On a controller stack whose other members are stopped, a bare cotal up in its root creates them again, empty, on that broker, the way a broker start does, and starts the other members. Its receipt says Space streams: created again, empty, on the running broker, and --json sets result.streamsRecreated. It does so only when every one of the space's streams is gone. A broker that lost only some of them keeps them as they are, and up refuses TARGET_NOT_FOUND, exit 2, naming cotal down --yes, then cotal up, whose broker start creates the missing ones. While the other members run, as when another machine deleted an open space under the stack, a bare cotal up finds the stack running and changes nothing. The refusals and status then say the space was deleted under its running stack and name cotal down --yes, then cotal up. They say so only when the broker answers that the chat stream is not found. A broker that answers no JetStream request has not lost its streams: nats-server stops JetStream after a store write it could not make and keeps the streams in its store. send and the other commands that read the space first then refuse DEPENDENCY_UNAVAILABLE, naming the write failure the broker's log records and its repair, and a broker restart brings the history back. To drop the space instead, run cotal down --yes in its root, then space forget. On a legacy root, run cotal down, then cotal up to start it again with empty streams.

use <space> selects the space commands target when none is named, in every project folder. It changes only the selection: it starts nothing and does not check the broker, so a stopped or prepared space can be selected and the command that targets it reports that. Selecting the explicit selection again is a no-op; selecting an adopted selection promotes it to explicit. A name that is not registered or prepared is refused with TARGET_NOT_FOUND, exit 2, naming the known spaces, and the selection stays. That refusal has no Mesh: heading, and its remedy names cotal use --clear only while a space is selected. Bare use reports the selection and whether Cotal adopted it automatically. Inside a project, it names the folder's space and how to reach it with --space <name> or cotal use --clear. use --json keeps its keys; folder identifies the local folder's space, not an override of explicit intent. cotal space and cotal status mark the folder as the target only when no explicit selection overrides it. A selection that names a space no longer registered is reported with a SELECTION_NOT_REGISTERED warning by use and space, and stays until use changes it. use --clear removes the selection, so a command targets its folder's space again. Its receipt names the space that was selected, and --json gives current: null with that previous. With nothing selected it is a no-op, exit 0. It takes no space name. A space stays selected through its cotal down: use then reports it as stopped, with its last operation, such as `cotal down`, completed, and names cotal up in its root. This also applies when a legacy space named after its folder keeps its registration after down. For that space, use --json reports currentRecorded: true and preparedState: "stopped" together. The space stays selected until use changes it. On a controller root, up --json gives result.selection, with current, the space selected after the start, and changed, which is true when this up selected its own space because no space was selected.

Target resolution

A command run without --space targets the selection. When the selected space's broker is down it refuses with TARGET_UNAVAILABLE, exit 2, and when the selection names a space no longer registered it refuses with TARGET_NOT_FOUND. Neither reaches another mesh.

A selection made with cotal use wins over every folder state, including a running, stopped, prepared or copied project. The note under Mesh: names that choice, including native spawn. The following folder precedence rules apply only when the selection was adopted automatically by the first up, registration or sign-in, or when nothing is selected.

A folder's space captures the commands run there only while it runs. Inside a project whose root has one registered space other than the selection, and whose broker answers, the command targets that space, as it does with nothing selected, and the note under its Mesh: heading, a refusal's included, says the selection applies outside the folder. A space cotal space create prepared there and no cotal up started, and one whose stack there is stopped, is the target of the commands about the folder itself only: cotal up, cotal down, cotal space show and the folder part of cotal status. cotal auth revoke-credential also targets the stopped one, because that space's account issued a credential minted there, and a space that never started holds no such account. Every other command run there targets the selection, and the note under its Mesh: heading says what this folder holds and the cotal up that starts it. When that stack's last up or down ended before it recorded an outcome, a member's unconfirmed stop can keep cotal up refusing, so the note names cotal status there instead, whose Next names the step that finishes or settles it. cotal status there leaves the note out, in --json too, when it shows that stop's block under This folder's space. A refusal there keeps that note whole, as for a selection whose stack is stopped, which names its own cotal up under Next. --json carries the same note in warnings as FOLDER_SPACE_NOT_RUNNING, whose target names the folder's space, its state (prepared or stopped), its root and the selected space, and cotal chat, which prints no heading, names the selection it joins with that note on stderr. cotal space show there calls a registered folder space whose broker does not answer this folder's stopped space. A folder that holds the records of a stack that runs from another folder or under another Cotal home, as a copy, a moved folder or one whose space name a later up took over, is not released to the selection: commands there refuse TARGET_UNAVAILABLE and name that folder or home, as they do with nothing selected. For a stack that runs from another folder, the refusal heads with Mesh: <space> and carries target.space, naming the space this folder's records name, as up and down there do. Nor is a folder whose own stack's last up or down ended before it recorded an outcome while a member still runs, as an up cut off before it registered the space leaves its broker. That stack runs in part, so every command there targets it, as with nothing selected, and the note under its Mesh: heading says the selection applies outside the folder. cotal status there reports it as Half started or Half stopped with its Next, which for that up is cotal down --yes and then cotal up --root <root>. Inside a project whose root has several running spaces, none of them the selection, the command targets the selection. Before it acts, it warns on stderr and in its JSON warnings with SELECTION_NOT_FOLDER_SPACE, naming those spaces and --space <space>. An empty --space value, such as --space "$S" with S unset, is refused with USAGE_INVALID, exit 1, by every command that takes --space, before anything is read or written. It never falls back to the selection. A --server URL with a user name or password in it, such as nats://<user>:<password>@<host>:<port>, is refused with USAGE_INVALID, exit 1, by every command that takes --server, before anything is read, written or dialed. The refusal does not repeat the value. The NATS client uses only the host and port of that URL, so the command would otherwise connect with the credential it resolves. Pass that credential with --creds, a login or the space's own trust instead. up refuses such a URL with its own message. The manager reads COTAL_SERVER when --server is unset, and refuses a COTAL_SERVER with a user name or password the same way, naming COTAL_SERVER. space add and meshes add refuse such a server in a connection bundle, and the meshes add prompt refuses one typed there, in the same words and with the same next step.

A prepared space whose project folder was deleted cannot start. A command that targets it, persona included, refuses with TARGET_UNAVAILABLE, exit 2, saying the folder no longer exists and naming cotal space forget <space>. cotal space create <space> --root <dir> then prepares it again. use, space show, up --space and space forget also say the folder no longer exists, and space show names the same forget and create steps in place of cotal up. If a matching stack journal in this folder shows that the project was moved instead, space show gives the move-back and adoption guidance described in Space inventory. Other commands that target the space from the renamed folder name the next step that up and down name there.

A stopped space that cotal up started is handled the same way when its folder was deleted. status says the folder no longer exists instead of naming cotal up there, and send and history refuse TARGET_UNAVAILABLE rather than report a missing seed. Both name moving the folder back or cotal space forget <space>. Run with --space from the folder it was renamed to, send and history give the refusal they give there without --space, which names the move and the way back.

With nothing selected, a command run in a project targets the space registered for that project's root. A root with no registration whose .cotal/ holds the stack journal cotal up writes is refused with TARGET_UNAVAILABLE, exit 2, naming the broker the journal recorded and cotal space create <space> --root <root>, which prepares the journal's space there again so that cotal up starts it. That is the state after an up that failed to start or a space forget, and the command never dials the default address instead. status there reads the machine, selects no space and probes no broker. A legacy root after its down, which drops its registration, is refused the same way, naming the space its account names, the address in the broker configuration its last start rendered and the bare cotal up there that starts it at that address again. A space named after its folder keeps its registration, so a command there is refused TARGET_UNAVAILABLE naming that root and cotal up, and status names the same step. A selection does not change these refusals: a root that holds such a journal or configuration and no registration, as a moved project does, is refused the same way and never reaches the selected space.

When the journal names running members but this Cotal home has no instance records for them, commands report the missing records. They do not infer that the stack runs under another home. If the original home's records were removed, the project's cotal down --dry-run and cotal down --yes provide the creation-pinned recovery stop. If another home still holds the records, use that home instead.

A copied or moved project folder keeps a stack journal that names the folder it was recorded in. space create <name> there refuses CONFLICT, exit 2, and names cotal space create <name> --adopt --root <root>, and status names the same command. --adopt takes the journal over: it rewrites it to name this folder, moves a broker store that lay under the recorded folder to the same place under this one, and records a stack that never ran here, so the next cotal up starts it from this folder with the copied store. When that store directory is present under this folder, it refreshes the recorded store identity from it, so a moved or copied store gives no replacement warning before startup, while a missing store or a replacement made after adoption still warns. It refuses with CONFLICT, writing nothing, when the folder's .cotal is a link, when the recorded folder still holds the journal, because this folder is then a copy of a stack that runs from there, when this machine records an instance of that stack, because the folder was then moved on this machine and moves back, and when the space is prepared or registered on this machine, where its Next names cotal space forget first. A copy brought from another machine and a folder moved after its record was forgotten are adopted. A folder renamed from a path that cotal up refuses, such as one with a tab in it, is told only to adopt, since moving it back would not start the stack. Without --adopt, nothing rewrites a journal.

With no --space, --server or --creds, nothing selected and no project in the folder, a command that several running spaces could serve asks which one when it runs in a terminal. The answer is the target of that one run, and the selection stays as it is; cancelling the question does nothing and exits 0. A script, a --json caller and --no-input are not asked: the command refuses with TARGET_AMBIGUOUS, exit 2, naming the running spaces. Every refusal of a target puts what to run next in error.remedy, apart from error.message, and names the space and root it concerns under target when they are known, as for a prepared space that is not started.

When this account cannot read or enter a project folder's .cotal/auth, for example because it cannot enter the folder's .cotal, the spaces the folder holds are unknown. A command that would target that folder, including through --server, refuses with DEPENDENCY_UNAVAILABLE, exit 2, and names the folder and the read error. When a folder on the way to .cotal/auth cannot be entered, the next step names that folder rather than .cotal/auth. The same refusal names each account record in .cotal/auth that will not load, such as an auth.json that is not JSON, and says to repair or remove it. It does not name running spaces or pick another space, and it changes no file. --space <name> still targets a space by name.

--creds <file> presents that credential to --server. Without --server, it goes to the broker its space is registered at and keeps that registration's TLS requirement. The space is --space, else the selected space, else the space of the project the command runs in, else main. Inside a project whose root has one space other than the selection, it is that space. A command never picks the only running space for a credential. A space not registered here is refused with TARGET_NOT_FOUND, exit 2, before anything is dialed. The refusal says whether it is the selected space, this folder's space or the default space, and a space other than the default is also under target. The default address is never assumed for a credential. The file is read and checked with the NATS client's own parser before anything is dialed, and the refusal names the file. A missing file is TARGET_NOT_FOUND, exit 2. A directory, an empty file and a file the client cannot parse are SCHEMA_INVALID, exit 1, with the cause: no complete JWT block, no seed block, an invalid seed, or Windows (CRLF) line endings. A file in a folder that another account can write, or below one, is refused PERMISSION_DENIED, exit 2, as auth mint refuses to write one there: the refusal names the folder, and its Next is one chmod, such as chmod go-w <dir>. A file that other accounts can read is still used, with a warning on stderr that gives the chmod 600 command. join --creds reads its file the same way. A credential the broker rejects is PERMISSION_DENIED, exit 2. When this machine holds the space's account and that account revokes the file's key, the refusal says when it was revoked with auth revoke-credential. Its Next is a mint with a new key, which for an agent file names the read and post channels and the role the file held. When the credential's own permissions name one other space, the refusal names that space, such as credentials rejected at <server>: <file> is a credential for space "<owner>", not "<space>", and its Next is --space <owner>. When --server named another broker than the one that space is registered at here, the Next says to use --space <owner> without --server, naming that broker. Keeping --server with --space <owner> refuses again, saying the space is registered at another address, and the Next is to drop --server or point it at that broker.

A manifest's space: is the target of native up -f and the new team check/boot/deploy routes. A --space that names another space is refused before anything is written. The old spawn -f manifest spelling no longer deploys; team deploy applies all-new live channel-only manifests or bounded static/open agent and mixed manifests. Reapply remains unsupported.

cotal meshes still lists, registers and drops meshes. space, space add, space create and space forget replace it, and its --json lines are the old shape. A bare meshes add on a terminal is still the guided form.

meshes [#mesh-registry]

cotal meshes [--json]
cotal meshes add                      # guided, on a terminal
cotal meshes add <space> --server <url> [--root <dir>] [--mode auth|open|user] [--tls] [--allow-unencrypted-overlay] [--force]
cotal meshes add <space> --mode user (--user-auth-file <bundle.json> | --from <https url>)
cotal meshes rm <space> [<space> …] [--force]
cotal sync [--idp <auth base URL>] [--json|--plain]
cotal status [--json|--plain] [--all] [-v|--verbose] [--space <s>] [--server <url>]
cotal status --components [--space <s>] [--server <url>]

cotal meshes is a legacy command. It still runs, and cotal help meshes still prints its help, but cotal help no longer lists it and completion does not offer it. Both bare cotal meshes and cotal meshes list show the registry without installing or refreshing connectors. cotal space lists the spaces, space add <name> registers one that runs elsewhere, including a user-auth space with --file or --from, and space forget <name> drops a registration.

Everyday command forms use positional agent names: cotal attach <name> and cotal stop <name>. For one-shot messages, choose one destination with --to/-t, --channel/-c or --role/-r: cotal send -t reviewer "Please inspect the patch". Message receipts do not repeat the body. They distinguish storage from delivery and say that no reply listener remains active.

Bare cotal shows a compact list of useful actions. cotal help shows the same list, then every command by group. cotal help --all, the spelling from before help listed every command, prints the same. A hidden command, such as a deprecated daemon entry, is left out and still runs. cotal cfg is the shorthand for cotal config. Its default view shows effective values and sources; config --verbose adds the storage path and revision.

Status starts with This machine, lists the spaces this machine knows under Spaces, then shows the selected space, this folder's maintenance journal under Maintenance when it holds one (its state, attempt and next step; maintenance in JSON), unsettled fresh and additive attempts in this folder when present, owned service records and useful commands under Next. Connection state, local process state and service replies remain separate observations. If the legacy broker PID file is missing or empty, the broker process row says no local process record. The connection row still reports whether the selected broker answers.

For the selected space, Default agent reports the harness a bare cotal spawn selects. The default persona's agent: pin overrides environment and saved harness preferences. If that persona cannot be read or validated, status reports the application as unresolved and includes a warning instead of presenting a harness preference as the launch choice. Non-regular persona paths, including named pipes, are refused without reading them.

This machine shows what is set up and what needs attention. The version line is always there. Agent applications is one line: the applications whose required executables are on PATH, and a count of the others, which cotal setup adds. An application's own rows, such as the Claude plugin, Claude Desktop and Claude skills, appear for an application that is set up and only when they are not current. When this machine has local broker records, such as a prepared space, a stack or a registration started here, the broker executable appears if it is missing or up refuses it. Prepared spaces count even when another space is selected or status runs outside their projects. Local trust and a stack journal also retain the row, including records that cannot be read or parsed. A client with only remote registrations does not need a local broker executable, so the compact report omits that row. --json, --wide, --all and --verbose keep the local executable diagnostics. The executable protection checks still apply before any broker launch. The dashboard appears when its record cannot be read. The extensions are one line, 11 extensions at 0.103.3, and an extension at another version is the only one named.

Spaces puts the space this report is for first, with its connection state, then one line per space: its name, its connection state and how it signs in. Only the space being reported is dialed, so the others carry no state and one note says that unselected spaces are not dialed and cotal status --all dials each. The broker address is not a group title here; cotal space show <name> names it. An account whose space catalog could not be refreshed is one line naming that account.

status --all and status --wide report every row in full: one row per known application, every extension with its version, the spaces grouped under their broker addresses with their origin, and the broker executable and dashboard rows. --all also dials every recorded broker; --wide dials no more than the default report. Use status --verbose for installation paths, extension records and the detailed local diagnostics. The default report does not include the agent roster; use ps or who. For an open or static-auth space, status shares one preflight observation across the selected space's rows and delivery check. A silent broker gets one confirming connect with the same eight-second budget as send, rather than a second preflight. It reads not answering in text and slow-link in JSON, distinct from unreachable. The deployment-attempt section lists at most 100 fresh and 100 additive local IDs, their returned/unsettled state and unreadable paths, with full readable coordinates in JSON. It appears only when there is something to inspect. A missing fresh summary does not prove the original broker never started; an additive intent does not prove which resources changed. This read grants neither retry nor stop authority. A fresh summary that names another folder, as one does after its folder was moved or copied, is listed with its recorded path and is not counted as unreadable. If the folder inherits the machine's home .cotal, status --verbose says that up there makes the folder its own project root. When the home holds a stack an earlier release started there, it also says that commands in the folder reach that stack until then.

A prepared space whose controller stack ran and was stopped reads as stopped, with its last operation and how it ended, such as `cotal down`, completed, and Next names cotal up in its root. A space that never started still reads as prepared but not started. A recorded file-store cap does not change the restart command because Cotal reserves no fixed capacity per space. meshes.currentStopped says whether the selection is such a stopped stack. A stack whose last up or down has no recorded outcome is not stopped, even when a member it launched still runs: the selection reads as prepared but not started, and the selected space names that operation.

Owned services use the saved controller definitions and instance records for the selected space. Instances are listed by definition name, then instance ID, in the text and in result.services.instances, so their order holds from one start to the next. Full instance IDs and execution hosts stay visible. Process observations and historical readiness are separate columns; neither a saved serving state nor a supervisor receipt becomes a fresh endpoint response or OS unit-state check. Legacy PID-file rows are labeled separately. On a root whose controller stack serves the selected space, its members are the stack- rows here, the legacy rows and the stored-state hint are omitted from the text report. When the stack does not answer or a member's process is gone, Next offers cotal up --root <root> first, with <root> quoted when a shell would split it. On a stack whose last up was --no-manager it adds --no-manager, and a manager record an earlier up left does not count as a stopped member. When a service of the space outside the stack runs one of this root's records, such as a delivery preset started after cotal down stack-delivery, up refuses until it stops, so Next first names that service's svc stop with its instance, as the refusal does, and then up --root. In open or static-auth mode, an unreachable --server address other than the recorded one says nothing about whether the stack answers. Next offers up --root only for a member whose process is gone, and names the failed address the way other commands' TARGET_UNAVAILABLE refusal does. On a static-auth root without a controller stack, started here with up, Next offers a bare cotal up in that folder first when its broker or manager exited, or when a clean down left every member stopped and the broker does not answer. It comes ahead of spawn, ps and the conditional store reset. When an earlier down, or a foreground up whose terminal closed, ended after it signalled the broker or the delivery daemon and before it saw that process exit, up and down refuse until that stop is abandoned. status then says so under the selected space, names the member, the earlier stop as operation <id> and the member's stop as stop request <request-id>, and offers cotal down --abandon-stop <request-id> --yes with that stop request ID, which their refusal names too, and the member's service status, in place of up --root and of a step that names cotal up. Run in that folder while another space is selected, status says the same under This folder's space with the same Next first, and leaves out the folder note that names cotal status. A stack there whose last up or down has no recorded outcome and that is not blocked settles when it starts, so Next names the cotal up that starts it there. --json carries the same as folder.stackBlock. A manager stop is decided by the manager's own receipts, which only up and down read, so status does not name it. An up or down that was interrupted before it recorded an outcome, and left some members running and others stopped, is named under the selected space as Half started or Half stopped, with the members on each side. Next then offers the command that finishes it first: cotal up --root <root> for an up, with the root shell-quoted when needed and --no-manager kept when it was chosen, or cotal down --yes for a down, followed by cotal up --root <root> to restart instead. The restart root is also shell-quoted after an interrupted down or when recreating deleted space streams. --json carries it as folder.stackUnfinished, with kind, id, running and stopped. An up cut off before it registered the space leaves the selected space prepared and not started, and status names its stack's block or unfinished operation and the same Next under it. When that up left members running, the next up cannot finish it, so Next offers cotal down --yes and then cotal up --root <root>. With another space selected, status in that folder still reports this stack, under This folder's space, and so does every other command there while a member runs. While the stack is blocked, the Delivery responder row says that up refuses until the block is cleared. The next bare up or down settles the interrupted operation with an OPERATION_SETTLED warning. When the stack reached that operation's end anyway, every member running after an up or stopped after a down, the warning says it was interrupted and where the stack stands, without calling it failed. When that up, team boot or down ran to its end and exited 3 with its outcome unconfirmed, the warning says it ended with its outcome unconfirmed instead. The journal records a team boot's start as an up, so the warning calls either one a stack start. A running stack-manager gets one probe of its manager endpoint, and the selected space's Manager row reads answering, not answering · stack-manager pid <pid>, or endpoint not checked when the probe could not be made or another manager instance answered. A manager that does not answer puts kill -KILL <pid> first in Next, because cotal down cannot stop it; once that process is gone, cotal down --yes records it stopped. A folder this account cannot read is one warning that names the folder and chmod u+rx on it, and nothing in it is read. Unreadable service record families make the report partial instead of becoming empty lists. Warnings retain a classified cause code, such as unsupported host observation, without native diagnostic bodies. These reads import no provider and start, stop, adopt or repair nothing. --all extends broker checks; this local owned-service section retains its explicit selected-space scope.

Registry output

meshes lists the meshes this machine knows; (default) after a name marks the current default a bare cotal spawn joins. A terminal too narrow for its columns gets one labeled record per mesh, as other tables do. Entries learned from a signed-in account are marked discovered. Their registration trust is stored under the account's private auth state, and the registry contains no session token or sentinel credential bytes. Commands resolve the catalog slug; a different human name is rendered only as a label.

meshes --json prints one JSON object per recorded mesh per line: space, server, mode, root, default (the row marked (default)), and origin (up, manual, or catalog for a discovered entry). A local or hand-registered entry also carries offline. A discovered entry is never probed, so it has no offline field. tlsRequired, events: "required" and a discovered entry's catalogName appear only when the record has them. An empty registry prints nothing and exits 0. The note about a default that matches no record goes to stderr, so stdout carries only rows, on a first run too. The table is presentation and is not a stable parsing target. meshes add and meshes rm refuse --json.

Unreadable records

A registry record this build cannot use is refused by name, never rendered and never skipped. One that does not parse, or is missing a field every consumer reads (server, mode, root, ts, space), makes every command that reads the registry refuse with SCHEMA_INVALID, exit 1, before it acts. The refusal names the file under target without repeating its stored values; meshes also says what is wrong with it. status is the exception: it lists the readable records, names the file and exits 4. Remove the file or restore the record; nothing repairs or invents a field for you. When the file is named for a space, the refusal names cotal space forget <space>, which removes that file. It reads no broker or folder from it, so it reports none. A registry directory that exists but cannot be read, such as one without read permission or a regular file in its place, refuses the same way, naming the directory, and meshes gives the read error. Only an absent directory is an empty registry. The folder of prepared spaces, ~/.cotal/prepared, refuses the same way when it exists and cannot be read, on every command that reads it, such as space, space create, use <name> and up. A file in its place is named as <path> is a file, not a folder, with the step that moves it aside. A record in it that does not parse or is not a prepared space record refuses only a command about the space its file is named for, such as use <space>, and names cotal space forget <space>. Other commands skip it with the warning PREPARED_RECORD_SKIPPED, which names the file and cotal space forget <space>, the step that removes it, and status lists it under meshes.unreadable and exits 4. A record removed between listing and reading is omitted from that listing. A keyed read also treats a record removed during its read as absent; parse, shape and other read failures still refuse by name. Recording or removing a mesh also sweeps the directory for an older-format record of the same space. Any error listing the directory for that sweep, other than an absent directory, fails the operation with that error. An unknown --space names the missing registration and points to cotal space, which also lists prepared spaces.

Account catalogs

An IdP may advertise a same-origin space catalog during login. Cotal reads the complete snapshot and adds every valid registration without a separate meshes add. A snapshot younger than five seconds is used without a request. After that, commands that resolve a mesh target conditionally refresh the saved catalogs. An operation targeting a discovered space refreshes only that space's account and refuses if that account fails. Operations targeting local or manually registered meshes refresh every account and continue. They warn once when an account's catalog starts failing and stay quiet while it keeps failing; the next failure after a successful refresh warns again. cotal status refreshes every account, never refuses on a refresh failure, and lists each account as fresh, updated, not-modified, no-catalog, or failed with its error. With no cached sign-in, catalog preparation reads without creating a control directory or lock. An explicit IdP without a cached login refuses with AUTH_REQUIRED. An unreadable sign-in or catalog cache refuses with DEPENDENCY_UNAVAILABLE before refresh or registry application. Both exit 2 and leave the cache untouched; diagnostics name the path without printing cache contents or parser excerpts. cotal sync bypasses freshness and reports added, changed, removed, unchanged, name collisions, and the spaces the catalog marks unavailable. --idp limits it to one signed-in account. It never connects to a broker or installs connectors. An empty or malformed --idp refuses with USAGE_INVALID, exit 1, before reading accounts. Use HTTPS, or HTTP on a loopback IP literal, without embedded credentials, a query or a fragment. --json gives each account under accounts with its idp, state, catalog, the six name lists, selectionCleared and error. An unavailable space keeps the registration this machine holds, which is also listed as unchanged; a command that targets it refuses with DEPENDENCY_UNAVAILABLE and the catalog's reason while its siblings keep working. An account whose catalog could not be refreshed keeps its last snapshot and is named in a CATALOG_UNAVAILABLE warning, so the result is partial, exit 4; when no account could be refreshed, sync refuses with DEPENDENCY_UNAVAILABLE, exit 2.

The registry is updated under the same lock that guards the catalog cache, so a command never lists a discovered space set that another command is still writing. The cache records a fetched snapshot as not yet applied before the first registry write and as applied after the last. If a command dies or is stopped in between, the next command applies that snapshot again before it can use it, with no request inside the freshness window.

The shared dispatcher applies this preparation to every command that declares both --space and --server as mesh-target flags, including commands registered by other packages and commands that declare their own equivalent flag objects. Daemon and startup commands that use those names only as configuration explicitly opt out. Registry-local meshes add and meshes rm never refresh a catalog. While the registry holds a record this build cannot use, the preparation neither refreshes nor applies a catalog, so the command's own checks run first. A snapshot left unapplied is applied by the next preparation after the record is restored or removed. A command that resolves its target through the registry still refuses the record by name.

Run on a terminal with the space or --server missing, meshes add is guided: it asks for the one thing that cannot be derived (the broker URL), probes it, and tells you what answered - open or requiring credentials. It then offers the spaces your --root already holds credentials for, and on an open broker the spaces that broker serves, states the mode as a fact about that broker rather than asking, and shows the exact record before writing anything. A broker that does not answer, or a space name already registered, becomes a choice rather than an error. When a broker answers at an address with TLS intent but this machine does not trust its certificate, the guided form says so with the flag form's handshake failure and its NODE_EXTRA_CA_CERTS step, and Cancel is the first choice, because Node reads that variable only when the command starts. An address the flag form refuses is refused with the same next step, such as the tls:// form of a host name, and the question that asks again shows no example address. For a name added by hand, the first choice is another name. Replacing a registered record then asks you to type y; Enter keeps No. Nothing is written before that last question, and a cancel at any question says nothing was registered. A name prepared or started on this machine, or listed by a catalog, is not offered for replacement. Anything you pass on the command line, --tls included, is taken as given and not asked again. Without a terminal - a script, an agent, CI - nothing prompts and the flag form's errors stand (COTAL_NO_PROMPT=1 forces that too).

cotal up and cotal down maintain their own records. meshes add registers a mesh they cannot speak for: one running on another machine, a shared broker, a hosted space. Like space add, it refuses a space name space create refuses, exit 1, with nothing written, even with --force. A mesh an earlier release registered under such a name still lists, shows and removes as before. --root is the folder whose .cotal/auth holds that mesh's credentials and whose .cotal/agents holds its personas. The default is the project you run it in. The registry stores that path, never a secret. --mode defaults to auth when the root holds the space's account record and to open otherwise. The broker is probed before anything is recorded, so a wrong address, or credentials that mesh will not accept, fails here instead of at the first spawn; --force records without verifying (and replaces a record added by hand). space show marks the forced registration's mode as unchecked, and whoami reports conditional access and exits 4 with MODE_NOT_CHECKED. A name that is prepared on this machine, or that this machine started or a catalog lists, is refused with CONFLICT (exit 2), with or without --force, as space add refuses it: cotal down finds a running stack through that record.

Registration trust

A hostname or public address is registrable only when the connection will require TLS. Pass --tls for TCP, or use a tls:// or wss:// URL. A ws:// address cannot satisfy a TLS requirement, even on loopback or with --force; use wss:// instead. Existing TLS-required ws:// records also refuse when dialed. Without required TLS, the refusal's next step is the secure URL form. The scheme is recorded as enforced intent, so every later dial through the record demands the handshake (and meshes add tls://… against a plaintext broker is refused at registration). Without required TLS the fence admits loopback literals, and private-overlay literals only with --allow-unencrypted-overlay, which records your acceptance that the overlay is protected only while its tunnel is up (Run a mesh). RFC1918 addresses are refused in both modes because a cafe LAN is private but does not belong to you. --force does not change these address rules.

A user-auth mesh registers from supplied pinned trust, never guessed: --user-auth-file takes the bundle exported where the mesh runs; --from asks before it dials the address at all, then fetches the /.well-known/cotal-mesh discovery document under that address (HTTPS only; a URL that already ends in that path is fetched as given), displays the pins, and asks again before adopting them. The document must parse as JSON under any content type the host serves it with; an answer that does not is refused with the URL and the content type that came back. Neither fetch follows redirects: a 302 can move a pinned fetch onto plaintext or onto another host, so it is refused rather than followed, and the pinned exchange must itself be an https:// URL, except for an exchange on this machine, where plain http:// is accepted for a loopback literal (127.0.0.1, ::1, any spelling of them) but not for localhost, which is a name rather than an address. Registration verifies that the exchange answers /health and /jwks as the pinned issuer. It also verifies that the broker refuses a bare connect; that auth-required refusal is the pass. The sentinel credentials land in a 0600 file under the entry's root; the registry records only the path.

Registry ownership

meshes rm drops records. It never stops a mesh. For a mesh running on this machine cotal down is the right verb, and rm refuses and says so, with or without --force, because cotal down finds a running mesh by its record. A stack cotal up started stays a prepared space at its root after that down, which meshes rm does not list or remove, so the refusal names cotal space forget <space> for it. --force drops a record only when its folder cannot be checked for a running mesh. A broker record that cannot be proven stopped counts as running, as it does for clean. A hand-added record is removed by meshes rm, by an add --force replacement, or by a cotal up that actually starts the broker for that same space, server and root, which becomes that mesh and so takes the record over (a cotal up for that space anywhere else refuses instead).

For several names, meshes rm loads the registry once, shares the legacy-file scan, and reads the selected default once. Each completed entry is reported and its selected default cleared before the next entry is attempted. A later removal failure does not roll back earlier removals.

Nothing that merely infers a record is stale from a dead broker touches it: an unreachable broker is listed offline and stays, whether cotal up or cotal meshes add wrote the record; a foreground up whose broker exits unexpectedly keeps its record the same way. A broker that answers at a record's address and refuses the connection is read the same way while another registered space names that address: the broker there is that space's, so the record is kept and the refusal is CONFLICT, exit 2, naming the space that holds the address, the cotal space forget <space> that frees it and the cotal up --server <url> that moves this one. cotal status shows that space as address held. Deleting the record would leave its folder naming no space, after which nothing there says which space its commands meant. A bare command does not treat that offline record as a running mesh; name it with --space to restart it. An operator command whose target is the selected space, or the space registered at its project's root, probes no other recorded broker. When it picks among the running meshes instead, it probes the recorded brokers once, and its mode check and its connect both read that one result. A cotal run from a managed seat with no --space also probes them once: its check for acting as the seat and the operator resolve that follows both read that result. Commands that inspect all spaces keep their existing probe behavior. cotal down / cotal clean all still drop an up record for the project they tear down; a hand-added one they leave alone even when it shares a root, because nothing on this machine could write it back.

A discovered entry belongs to the normalized IdP origin and proved subject that supplied it. Local teardown, cleanup, and liveness pruning do not remove it. A manual or locally started entry with the same name wins and remains untouched; that discovered name is reported as a collision. Logging out removes only the discovered entries owned by that account.

Required event planes

cotal meshes and cotal status print events: required for a registration carrying policy: { events: "required" }. On that space, foreground spawn, detached spawn and manager starts that host a native harness cannot opt out or launch without an event plane. --no-events is refused with the space named. A connector without an event plane is refused with both the space and connector named. A session whose own grant omits events.<owner>.<actor> is refused before joining and the message names a full-row actor grant repair. A running seat whose event plane stops keeps running and keeps its mesh connection on that space as on any other; the connector re-establishes the plane itself and reports every failure with the delay before the next attempt. A seat the manager resumes from a preserved cut meets the same rules as a fresh spawn: a seat retained with --no-events, or on a connector without an event plane, is refused, and a resumed seat carries the requirement in its launch material.

join, one-shot sends and passive protocol views host no native harness turns. They publish no AG-UI runs, regardless of who drives their input. Required events do not turn terminal messages into agent runs or copy channel and DM text into an event stream. This launch policy is not an additional broker authorization boundary. The broker still enforces each endpoint's grants.

An explicit cotal use selection applies from every directory, including the project folder of a running space. There status reports the selected space under its Mesh: heading and names --space <space> or cotal use --clear to reach the folder's space. Only an automatically adopted selection yields to a running project's space. In that case, status reports the folder's space under its Mesh: heading and a This folder's space section, and says the selected space applies outside the folder. --json names it in target.space and in meshes.folder, which cotal space --json gives as folder. In the folder of a space that is prepared or stopped, status reports the selection instead, and the line under its heading names what the folder holds and the cotal up that starts it; meshes.folder is then null. A folder whose stack is half started or half stopped, with a member still running, counts as a running space's folder here. In a copy or a moved folder, where the commands refuse under the space the folder's records name, status reports that space under its Mesh: heading, marks it in the Spaces list when it is registered, and says what the folder holds in a This folder section, with the step those commands name under Next. --json names that space in target.space and selected.space, and the recorded folder in selected.recordedRoot. status is a read-only report in this order: this machine (the installed cotal-ai version, NATS and each named integration), the installed extensions and their versions, this folder's .cotal/, the recorded meshes, the selected mesh (its connection, the delivery responder, its channels and membership feed), then the hints. It lists no roster; cotal ps lists managed seats. Stale Claude skills and out-of-date .agents skills recommend cotal setup --skills, not unscoped cotal setup. status takes --space / --server to pick the mesh to inspect; it starts nothing.

When status would suggest restarting the selected stopped local stack, status checks the recorded root's default .cotal/channels.json with the same validation as up. An invalid file is named under Next with the repair to make before restarting. The broker still reports as unreachable when dialed. The check does not change the file or start the stack. In --json, selected.channelSeedBlocksRestart is true when this check finds a blocker, and hints names the file and its repair.

Broker probes

Status displays broker addresses without URL user information, query parameters or fragments, including component facts. Saved addresses and connection inputs are unchanged. An address that cannot be displayed safely is null in JSON, unavailable in text, and names a BROKER_ADDRESS_INVALID warning with a partial result. Its broker component is refused.

Only the selected mesh is checked. Its row under Spaces dials its address with its recorded TLS requirement, and every other row carries no connection state, under the note that says what was dialed. When --server names another address, that address is the only broker dialed, and the selected mesh's row carries no state either. In --json each of those rows is not-checked. --all checks every recorded mesh, including discovered ones, each with its own recorded TLS requirement. Each row then shows the check of its own address, the selected mesh's row included when --server names another.

JSON report

The nats row in folder.processes keeps its raw PID-file observation in legacyPidfile, with state, pid and detail. Its source is legacy-pidfile for a legacy root or owned-service for this folder's controller stack. For a legacy broker with no recorded PID, a missing or empty PID file gives the summary state: "not-recorded" and pid: null. For a controller stack, the summary state, pid and detail come from the owned broker's process observation. ownedService carries its definition, instanceId, observedProcess, recordedState and pid, or null when no instance was read. An unstarted stack with no instance means stopped. A missing retained instance or an unreadable or ambiguous owned record means unreadable with a partial report, without substituting the PID-file state. A foreign host or unresolved launch means unknown. The observations are not an atomic snapshot and do not prove broker readiness.

status --json writes one envelope whose target is {space, scope}, where space is the selected space or null and scope is selected or all. Its result is the report the text draws:

Field Holds
kind infrastructure
machine version, install (kind and root), nats (path, bundled or missing), integrations (each {name, state, text} a connector's setup reports), connectors (each {name, requires, missing}), skills (state: current, not-installed, behind or unreadable), and web (installed, url and the error of each when it could not be read)
extensions root and items, each {package, label, version}
folder root, auth (state: space, spaces, none or unreadable), personas (root, default: valid, invalid, missing or unreadable, demo and error), launches (whether a bare spawn launches from this folder's catalog; null when no mesh resolves), processes (each {name, state, pid, detail}, state one of running, stopped, not-recorded, not-serving, unknown or unreadable), storedState, noManager (whether this root's controller stack was started with --no-manager) and managerService (the service of the space, outside that stack, whose process runs this root's manager, as a manager preset started there does: its definition and instanceId, or null), heldServices (the services of the space, outside that stack, whose processes run this root's records, as up names them before it refuses: each definition, instanceId, record and pid; null when those records could not be read)
meshes current, folder (this folder's running registered space when a command there targets it, else null), unreadable (the registry directory, a record, the current-mesh pointer, or the prepared spaces folder or a record in it, that could not be read, or a pointer that is empty, each as {file, error}), items (each with space, server, mode, root, origin, tlsRequired, eventsRequired, current and check: reachable, unreachable or not-checked) and catalogs (each {idp, account, state, error}, where account is the IdP subject the error line names)
selected {resolved: false, code, message} when no mesh resolves, where message states why and hints carries the step (code is registry-unreadable when the registry directory or a record could not be read, and a not-started prepared space adds its space and root); otherwise the target's fields, connection (ok or the reason it failed; on a user-auth mesh reachable or unreachable), login, deliveryResponder (bound, unbound, stale or unknown, and null on an open mesh with no delivery lease), snapshot, channels, membershipFeed and spaceStreams. spaceStreams.state is present, absent or not-checked; it is read for an auth or user space and an open space this machine started. When absent, root is this machine's stack of the space and stack is running or stopped, each null when unknown. storedBytes is what the space's account holds in the broker's JetStream file store, null when it was not read
services Selected-space local owned records: space, state (read, partial or not-checked), non-atomic observedAt, public definition/instance projections and explicit scope. An unreadable family is null; stored readiness is historical. Older serialized snapshots may omit this observation, which is not an empty inventory.
stackManager The selected space's running stack manager: instanceId, pid and endpoint, which is answered, not-answering or unchecked. Absent when no stack manager runs
store What the selected space's running local broker logged about its JetStream store: state write-failed with pid, log, at, cause, path and jetStreamDisabled, true when the broker then disabled JetStream; full with used, cap and path when the space holds more than its broker's recorded cap; damaged with pid, log, at and the broker's warning when it logged damage in a stored file; none-recorded with pid and log; or not-checked with a reason. Absent when no space resolves
hints The hints, in the order the report prints them

store covers only a broker whose log is on this machine: a controller stack's stack-broker instance, or the broker a legacy root records in .cotal/nats.pid with its log .cotal/nats.log. nats-server reports a stream's write error natively only through healthz, which needs a system-account user, so status reads a bounded tail of that log instead and keeps only lines tagged with the running broker's process ID since its last start. When the broker logged a store write failure, such as a full disk, the selected space shows a Store row with its time, cause and file. This includes the broker's permission-denied warning and stream-write errors from a file-size limit. The broker keeps that error until it restarts, so messages sent meanwhile are not stored. The first Next is cotal down, to run once the logged cause is fixed: write access to the store again for a permission error, or free space for a full disk. Then cotal up starts the broker again. When the broker also disabled JetStream, which store.jetStreamDisabled shows, the manager's stop cannot be recorded, so the Next starts with kill -TERM <pid> for the stack's manager on this host, then cotal down --yes and cotal up.

When the broker logged damage in a stored file since it started, the Store row reads damage logged with its time and the broker's own words. The recognized warnings cover a message block whose records do not parse (indexCacheBuf corrupt), which the broker rebuilds without the messages from the damage on; a stream whose recovery rolled back past what a consumer had delivered; and a stream metafile that fails its checksum, which the broker does not load. It keeps serving what it can still read, so history holds only that. These warnings do not necessarily populate the STREAM.INFO lost-data field. For a controller stack the Next is cotal service logs stack-broker. status repairs nothing.

When the space holds more bytes than the --max-file-store cap this machine recorded for its broker, the broker refuses every write, so the Store row reads full with the bytes stored, the cap and the store's path. Its Next names the route up names, which keeps the history: kill -TERM <pid> for the stack's manager on this host, as a full store refuses its stop, then cotal down --yes and cotal up --max-file-store <bytes> with a larger cap. It does not name cotal history clear, which can leave the store over its cap. From another folder, the Next names the stack's folder to run cotal down --yes in, and up carries --root <dir>. The Delivery responder row then says that the full store refuses the daemon's lease, so up starts the daemon only once there is room. The bytes are the space account's own, as $JS.API.INFO reports them; the cap counts every account on the broker. A broker started without a cap sizes its store from the free disk, and status does not compare that.

deliveryResponder is stale when the ready row in the delivery lease belongs to a daemon that is gone. That includes this folder's own daemon once its recorded process has exited without releasing the row, as after a kill. The row expires on its own within 30 seconds. The delivery responder line then says the delivery daemon died and its lease has not expired yet, that spawn, retirement and the durable backstop wait until a new daemon binds while joins, DMs and live posts can still work, and that cotal up restarts it, since up waits out the lease first.

With no delivery daemon serving, as after cotal down stack-delivery, deliveryResponder is unbound. The delivery responder line says spawn, retirement and the durable backstop wait until a daemon binds, while joins, DMs and live posts can still work, and that cotal up starts it.

When a controller stack's delivery member runs but holds no delivery lease, deliveryResponder is unbound, and the delivery responder line names the member's pid and says it is starting or not responding. status cannot ask the daemon which. Next names cotal service status stack-delivery, then cotal down --yes, which kills a member that does not exit, and cotal up.

Partial reads

An unreachable broker, a stopped process or an unbound responder is a state the report names, and status exits 0. An open mesh runs no delivery daemon, so when it records no delivery lease its delivery responder row says the responder is not used and suggests no command. A controller stack started with --no-manager gets a Manager row saying it runs none by choice and that bare cotal up adds it. A part it cannot read is named on its row and as a warning, and the run is partial with exit 4: a PID record, the folder's trust material, the delivery-aware marker, the connectors, the skills bundle, the web records, a persona catalog, the mesh registry or one of its records, the current-mesh pointer, a user-auth login, or the selected mesh's channels or its owned service definition/instance records. Only an absent catalog, registry or pointer reads as empty or unset; an empty pointer is named too. A registry directory or record that cannot be read also leaves the selected mesh unresolved, because resolution refuses it, and the readable records are still listed. A corrupt or unreadable extensions manifest is refused while loading the command surface, before this report can run. The manager row asks the service endpoint once: a live process that does not answer is not serving, and a probe that could not be made leaves the row running · service unchecked. A broker that takes the connection and does not answer, as a stopped one does, leaves it unchecked too, and status still exits.

Local records

The local auth reader uses a stripped signer only when both split trust records are absent. The load refuses dangling and looping links at either record even when an older stripped signer is present. A process row whose PID record exists but cannot be read, or exists under both its current and a pre-upgrade name, reads pidfile unreadable with the error, and the other rows still print. A live manager whose delivery-aware marker cannot be read keeps its row and names the failure as delivery-aware marker unreadable with the error. The Web process row prints the address the selected mesh's dashboard recorded once it was listening, while the PID in its web.pid is alive. The dashboard that holds web.pid picks the record. A dashboard started with cotal service start writes its session record beside its service startup receipt, and status finds that record through the web service instance whose recorded process is that PID. Any other holder is read from web.session. Neither record is read in place of the other. A web.pid, session record or service instance record that exists but cannot be read is named on the row with the error. Otherwise it reads down, or not installed without the web extension. Status and the cotal setup card count the web extension as installed only when a package in the extensions manifest provides web and that package is on disk. A web package record that cannot be read, is not JSON or has no version is named on the Web extension row and on the card's web row, after the dashboard's address when it is listening and beside an unreadable web.pid or session record. The Web process row still prints, and reads down unless the dashboard is listening.

Account state

If a refresh fails, status may still show the kept catalog bytes for diagnosis. It labels them stale with the last successful snapshot timestamp and the refresh error. It never calls that state synchronized or online. If a selected discovered space vanishes from a successful snapshot, the selection is cleared and the command reports that no default is selected.

For a user-auth mesh the selected-mesh section reports the login status works as: the signed-in subject when this machine holds a cached session for the entry's pinned IdP, or the exact cotal login --idp <url> line when it does not, with no network round trip either way. A locally provisioned space also shows the actor grant row; a discovered or registered remote entry reports the grant as not checkable on this machine, because the ledger runs where the space was provisioned. --components on a user-mode target probes delivery as that same signed-in login, never a static mint. The broker row checks that the registered address is reachable and includes any observed local store write failure or full store. It does not present the login. The manager status probe uses the manager-caller view cotal spawn already exchanges for that login. When this machine's manager process is live, the exchange is pinned to the instance id that process persisted. If that id is not known, or a different instance answers, the row is refused and is not reported as this process serving. An answer names the instance that gave it. A probe refused before any answer says so, and does not invent an instance. When this machine has no manager process, an unpinned answer is reported as serving and the row names that instance. A spawn holder carries status on the pinned instance. ps and slots are not part of this probe. When the login or that view cannot supply a credential, the manager row says why instead of printing the broker's refusal of an unauthenticated probe.

Persona rows name the catalog they describe. If this folder and the selected mesh use different catalogs, status names both and marks which one spawn launches from. A green default means the file passes the same agent-file loader spawn uses; a present but invalid file is reported as invalid.

cotal status --components prints the report, then a fail-loud per-component health pass. It takes no --json, --plain or --all. It reads each component's own control surface, rather than treating a PID, a lease, or a successful probe of a sibling as proof that the component serves. It prints one of serving, absent, not-serving, or refused for each component and exits 0, 1, 2, or 3 respectively (the highest observed state wins). The optional dashboard prints not-installed when its extension is not installed, or not-started when it is installed but has no process record or unsettled owned instance. Both exit 0. The component pass uses the same selected space as the report above it. A trailing slash in the broker URL does not change which startup records the pass reads. That exit replaces the report's own, so a partial report followed by a clean pass exits 0:

  • manager: local PID record, its liveness-lease holder and PID, then the manager's own typed status service reachability from this host. A manager that answers without reporting static reconciliation says static reconciliation not reported by this manager build; the line stays visible even when the manager is otherwise serving. A row that reached no manager does not carry it. If the service does not answer and the local PID is dead, the manager reads absent even before its lease expires. A lease without a local PID record still reads not-serving. A stack intentionally started with --no-manager reports not-started and exits 0 when no manager answers and no manager lease remains. Legacy starts record that choice against the broker's creation identity, so it does not survive as proof for a different broker process.
  • delivery: local PID record, its ready lease (ready is the daemon's own bound-control signal), and the latest renewal.<spaceKey>.json adoption verdict, the record of the space the command was asked about, keyed per space the way the pidfiles are. A re-signed credential and a broker-accepted adoption stay distinct facts. A root-only renewal.json left by an older build names no space and is never read as any space's verdict (doctor auth names it as a leftover). On an open mesh with no delivery process record or lease, delivery is not-started and does not fail the check. A managed delivery credential exposed to other local readers makes this row refused, with its native permission repair. The ordinary report names that credential as an unreadable part and exits 4 instead of silently skipping lease-holder verification. An unreadable renewal record or a recorded adoption refusal makes delivery refused, even when its responder is bound. Bare status reports the same finding and exits partial rather than healthy.
  • web: not-installed when the dashboard extension is not installed and no PID record exists. An installed dashboard with no PID record or unsettled owned instance is not-started, which does not fail the check. A dead PID with a stale record is still absent and exits 1. An owned dashboard instance that exited without a confirmed stop is also absent, even if its shutdown removed the PID file. Confirm its stop with cotal service stop web --yes. Otherwise, the local PID record, then the /api/meta response at the address the dashboard recorded once it was listening, which must name the same PID. The holder of web.pid picks the record, as on the Web process row: a service-run dashboard's own session record, found through its web service instance and named on the row as service instance <id>, or web.session for any other holder. The probe presents the readiness nonce recorded beside that address, the one credential the dashboard accepts on /api/meta. The probe follows no redirect. An answer with a status outside 2xx, a 3xx included, is not-serving, and the row names that status, such as HTTP 401. A live PID with no recorded address (the dashboard is still writing it, or an earlier build started it), or an unrecognizable process record, is refused, not a green default-port guess. A session record or service instance record that exists but cannot be read is also refused, and the row names the read error.
  • broker: the registered mesh URL dialed from this host with its recorded TLS requirement. An observed local store write failure or full store makes it not-serving, with the store failure in its facts, even if that URL is reachable. For a locally owned stack, a missing or dead broker process is absent, not not-serving. A cleanly stopped controller target reports absent and exits 1 without dialing another space. For open and static-auth plaintext NATS targets with no absent local process, the probe also checks JetStream and the recorded authentication requirement. An unauthenticated substitute for a static-auth broker is not reported as serving. When the address and process identity match this space's running local broker, missing JetStream does not trigger the substitute-broker remedy. A request that fails after the broker disables JetStream keeps its store write diagnosis and history-preserving repair.

When a stopped local broker's address accepts a connection without a NATS greeting, status and read commands name the occupied address and recommend stopping that listener or starting on another port. They keep the space's registration.

When --server matches several registered spaces, add --space <name> to choose one. Selecting a default with cotal use <name> applies only after removing --server. whoami recognizes equivalent registered URL spellings, including a trailing slash or scheme case, without treating another transport as the same registered address.

An unreadable component PID file is refused, and its row names the file path and read error. A malformed PID file is not a stopped process. Bare status names the uncertain record and exits partial. An unreadable mesh registry record produces a target refused component row and exit 3. A missing or empty PID file still means no local process record. PID records with creation pins are checked against the live process identity. A reused PID is stale, not running, and cannot keep a dead delivery daemon's ready lease bound. Unknown or unreadable identity pins refuse the component check rather than claiming liveness.

If a user-auth exchange returns a bearer whose principal cannot be decoded, the component probe reports the shared auth-service build and restart guidance instead of a bare JSON or missing-claim error.

absent means Cotal has no live local component record (or has a stale record); not-serving means the component record is live but its service/readiness surface did not answer or is not ready. Those are intentionally separate exit cases. A failed or unreadable probe is refused, never an absent component or a clean zero. A broker that takes the connection and does not answer, as a stopped one does, refuses the manager and delivery probes, and the pass still exits. A PID record that exists but cannot be read, or exists under both its current and a pre-upgrade name, refuses only its own row. A record that its component removes while the pass runs reads as absent.

The auth-service start, status and stop paths share the same PID-file resolution rules. An unreadable record directory refuses the start; it is not treated as an absent pre-upgrade record.

Each component keeps one line when piped or when its row fits the terminal. On a narrower terminal, its facts stack below the name and verdict, wrapping at spaces. A single identity, path or command wider than the terminal stays whole. Verdicts and exit codes do not change. A control character inside a reported reason, such as a newline in a stored row's field name, prints as its \uXXXX escape.

Registration [#registration]

See the current command contract for this behavior.

Default selection [#default-selection]

See the current command contract for this behavior.

Legacy registration [#legacy-registration]

See the current command contract for this behavior.

status [#status]

See the current command contract for this behavior.

Report scope [#report-scope]

See the current command contract for this behavior.

Component health [#component-health]

See the current command contract for this behavior.