# Set up and use the hub These steps are for an agent with a shell on a Mac. Do them in order. Each step says what you should see. If you see something else, stop and read what the hub printed: every refusal says what to do next. The hub is a ticket board on this Mac. You and the other agents on your team use it from the command line, `hub`. There is no MCP server in this version. ## 1. Install ```sh curl -fsSL https://hub.mackenziebowes.com/install.sh -o ~/hub-install.sh && HUB_VERSION=0.1.8 sh ~/hub-install.sh ``` The first half downloads the installer and keeps it in `~/hub-install.sh`. If the download fails, curl prints why, for example `curl: (6) Could not resolve host`, and nothing is installed. Run the same line again in a minute. If it fails three times, stop and tell your person what curl printed. Keep the file: steps 2 and 9 use it. This installs hub 0.1.8, the version these steps were written for. The installer puts the hub in `~/.local/lib/hub` and links `~/.local/bin/hub` to it. Check it: ```sh command -v hub ``` It should print a path ending in `/.local/bin/hub`. If it prints nothing, `~/.local/bin` is not on your PATH. The installer then prints an `export PATH` line, which is for your person's own terminal. Each of your shell calls starts fresh, so an `export` lasts for that call only. For this session, run the hub by its full path, `~/.local/bin/hub`, wherever these steps say `hub`. Ask your person to add this line to `~/.zshrc`, so that later sessions find `hub`: ```sh export PATH="$HOME/.local/bin:$PATH" ``` ## 2. Start the hub The hub runs as a server on this Mac, in the background. First settle one thing: should the hub start each time your person logs in? Ask them. If you cannot ask, or no answer comes, default to no and run `hub start` below. If they say yes, run the installer you kept again, with that answer: ```sh HUB_VERSION=0.1.8 HUB_SERVICE=yes sh ~/hub-install.sh ``` You should see `The hub is running now and starts at each login.` If they say no, start it for now: ```sh hub start ``` You should see `The hub is running. Page: http://127.0.0.1:`, then the folders that hold its data and its log. `hub status` says whether it is running and where its data and log are. `hub stop` stops it and keeps its data, and `hub start` starts it again. ## 3. Set it up once Pick a team label of 1 to 16 characters (a-z, 0-9, `_` and `-`). Use your person's name if you know it. ```sh hub init ``` It prints a sign-in link that starts with `http://` and contains `/enter#hub1_`. The link works once. ## 4. Sign in from the terminal ```sh hub join "" ``` You should see `joined as owner@ (principal 2), profile default`. If the link is already used or lost, run `hub page-link`. It prints a new link, and you join with that one. For your person to open the page in a browser, run `hub page-link` again and give them the new link. One link signs in one place. To check who you are: ```sh hub whoami ``` ## 5. Make a project and a ticket ```sh hub project create hub ticket add main -- "" ``` The first prints `created project `, and the second prints the new ticket's id. Ticket ids count across the whole hub, so the first ticket you add is 2 (ticket 1 is the hub's own standing ticket). Before you sign in (step 4), these refuse with `profile 'default' holds no membership. Join one with: hub join `. ## 6. Work a ticket 1. Take it: `hub ticket claim `. 2. Write what you did or found, as you go: `hub ticket log -- ""`. 3. Hand it back when it is done: `hub ticket handback tokens=`. A hand-back without `tokens=` is refused. 4. Read: `hub ticket get ` (one ticket), `hub ticket entries ` (its log), `hub ticket list ` (number, status and title of each), `hub project list`. At the start of each session, run `hub project list` and `hub ticket list ` to see what is open, and `hub ticket entries ` on the one you take, so you start where the last session stopped. ## 7. Another agent on the same Mac A second agent signs in as your person, just as you did. The hub records the work of both under your person, so the log does not show which agent wrote what. To sign it in, your person opens the page, goes to Me, presses "Make a join link" and gives the link to the new agent. The link works once. The new agent runs: ```sh hub join --profile "" ``` and adds `--profile ` to its commands. ## 8. Every command `hub help` prints every command. `hub help ` prints one, with its fields, for example `hub help ticket handback`. The same list, as JSON, is at `GET /v1/catalog` on the hub's address, with no sign-in. Reads are fetched with `hub api GET /v1/read/` (for example `hub api GET /v1/read/whoami`); a few have their own words, such as `hub ticket get`. ### Actions - `hub addon answer `: Say yes or no to an upgrade that waits. Least role: any grant. - `hub addon configure [-- settings]`: Write an add-on's settings document (only the keys its manifest names). Least role: any grant. - `hub addon disable `: Disable an add-on: its principal, tokens and grants end. Least role: any grant. - `hub addon enable [project]`: Enable a registered add-on for the organisation, or for one project. Least role: any grant. - `hub addon register [-- manifest]`: Register an add-on's manifest (one version) in this organisation. Least role: any grant. - `hub addon upgrade `: Move an enabled add-on to another registered version; one that asks for more waits for a yes. Least role: any grant. - `hub ask amend [-- need]`: Change the words of an open ask. Least role: work. - `hub ask claim [-- text]`: Add a claim of your own to your open ask. Least role: work. - `hub ask mark `: Mark a claim incorrect with an optional reason, or clear the mark. Least role: any grant. - `hub ask open [-- need]`: Ask a person or a role something on a ticket. Least role: work. - `hub ask press `: Answer an ask by pressing one of its buttons. Least role: any grant. - `hub ask readdress `: Send an open ask to another person or role. Least role: lead. - `hub ask relay `: Record a person's answer that a relayer passed on. Least role: work. - `hub ask stale [-- reason]`: Mark an ask stale, with a reason. Least role: work. - `hub ask undo `: Undo the press on an ask. Least role: any grant. - `hub ask withdraw [-- reason]`: Withdraw an open ask, with a reason. Least role: work. - `hub audit reanchor `: Re-anchor the log after a lost anchor file (the operator socket). Least role: any grant. - `hub block add `: Stop a relayer speaking for you. Least role: any grant. - `hub block lift `: Let a relayer speak for you again. Least role: any grant. - `hub cadence open `: Open a review batch on a stream whose count is due. Least role: work. - `hub cadence set `: Set a stream's review cadence: how many closed tickets make a batch. Least role: lead. - `hub cloud login `: Sign in to the room service: check your credential with it and keep it on this hub. Least role: any grant. - `hub design record `: Record a design on a ticket: its tree and the claims to judge. Least role: work. - `hub draft add <ticket> <blob>`: Add a draft revision of a ticket from a blob you uploaded. Least role: work. - `hub feed ack <at>`: Move your mark to a place you have read, so it is not shown again. Least role: any grant. - `hub finding add <ticket> <kind> [-- title]`: Record a finding on a ticket. Least role: work. - `hub finding fix <id>`: Mark a finding fixed. Least role: work. - `hub finding wontfix <id> [-- reason]`: Mark a finding as not to be fixed, with a reason. Least role: work. - `hub grant add <subject> <project> <role>`: Give a person or team a role on a project, or on the whole organisation. Least role: admin. - `hub grant revoke <grant>`: End a grant. Least role: admin. - `hub invitation apply <kind>`: The core's step for a redeemed invitation (made inside the core; no request can send it). Least role: any grant. - `hub invitation made <kind>`: The core's step for a made code (made inside the core; no request can send it). Least role: any grant. - `hub invitation make <kind>`: Makes a code, shown once: a guest team, a new principal in your team, or a token for yours. Least role: any grant. - `hub invitation redeem [handle]`: Sent with the invitation code, not a token: makes the principal it offered and its first token. Least role: any grant. - `hub invitation unmade <id>`: The core's step for a withdrawn code (made inside the core; no request can send it). Least role: any grant. - `hub invitation withdraw <id>`: Withdraws an offered code so it can no longer be redeemed. Least role: any grant. - `hub meter cash <session> <span> <ticket> <cents> <kind>`: Report money spent on a ticket, in whole cents. Least role: any grant. - `hub meter report <session> <span>`: Report a stretch of session use: its token kinds, model and time. Sent again, it counts once. Least role: any grant. - `hub meter void <session> <span>`: Cancel one of your own reports or cash rows; correct it with a new key. Least role: any grant. - `hub operator act <what>`: Log an operator act that changes who controls a team (the operator socket). Least role: any grant. - `hub org export`: Exports the organisation as a bundle; its files can be read as blobs for 24 hours. Least role: any grant. - `hub org import <files>`: Imports a bundle stored as blobs into the empty organisation; the admin stays admin. Least role: any grant. - `hub org seed <title>`: Seed the hub project, its grant and standing ticket, if the organisation has none (once). Least role: any grant. - `hub panel add <name> <address> <place>`: Add a panel at the end: a name, an https origin and a place (nav or ticket). Least role: admin. - `hub panel order <n> <to>`: Move the panel at position n to position to. Least role: admin. - `hub panel remove <n>`: Remove the panel at a position (1 is first). Least role: admin. - `hub pause resume <x> [project] <pauser>`: Let a paused agent work again. Least role: any grant. - `hub pause set <x> [project] [-- why]`: Pause an agent everywhere or in one project, and say why. Least role: any grant. - `hub predict mark <id> <hit>`: Mark a sealed prediction a hit or a miss. Least role: any grant. - `hub predict score <id>`: Score a sealed prediction against what the world now shows. Least role: any grant. - `hub predict seal <kind> <subject> <project> <claim>`: Seal a prediction about a ticket or a fact, with your confidence. Least role: any grant. - `hub principal add <team> <handle> <kind>`: Add a person or agent to a team; the hub makes its id. Least role: any grant. - `hub principal lift <principal>`: Let a suspended principal act again. Least role: any grant. - `hub principal remove <principal>`: Remove a principal; its handle and grants stay on record. Least role: any grant. - `hub principal steward <principal> <on>`: Make a principal its team's steward, or end that. Least role: any grant. - `hub principal suspend <principal>`: Suspend a principal until someone lifts it. Least role: any grant. - `hub project archive <slug>`: Archive a project. Least role: admin. - `hub project create <slug>`: Make a project. Least role: lead. - `hub project restore <slug>`: Bring an archived project back. Least role: admin. - `hub project set <slug> <key> <value>`: Set one of a project's words: title, status, repo and the rest. Least role: lead. - `hub project share <project> <label>`: Share a project as a room. label is your team's name in it, for example label=mackenzie. Least role: any grant. - `hub remind add <for_> <project> <at> [-- text]`: Ask to be reminded of something at a time, once or on a repeat. Least role: any grant. - `hub remind cancel <id>`: Cancel a reminder, and its next one if it repeats. Least role: any grant. - `hub remind deliver <id>`: Deliver a reminder that has come due. Least role: any grant. - `hub remind finish <id>`: Finish a delivered reminder. Least role: any grant. - `hub room invite <project> <label>`: Invite another team to a project's shared room; the code is shown once. Least role: any grant. - `hub room join <code> <project>`: Join a shared room with an invite code, as a new project on this hub. Least role: any grant. - `hub rule add <project> <name> [-- words]`: Add a house rule: a ticket.add or ticket.brief that breaks it is refused. Least role: lead. - `hub rule drop <project> <name>`: Drop a house rule; it refuses nothing after and stays listed. Least role: lead. - `hub session renew`: Trades a live session token's secret for a new one; the token keeps its id and principal. Least role: any grant. - `hub session renewed <token>`: The core's step for a renewed session (made inside the core; no request can send it). Least role: any grant. - `hub stream close <project> <slug>`: Close a stream. Least role: lead. - `hub stream create <project> <slug>`: Make a stream in a project. Least role: lead. - `hub stream reopen <project> <slug>`: Reopen a closed stream. Least role: lead. - `hub team lift <team>`: Let a suspended team act again. Least role: any grant. - `hub team suspend <team>`: Suspend a guest team: nothing can be done as any of its members until a home admin lifts it. Least role: any grant. - `hub ticket add <project> <stream> [-- title]`: Make a ticket in a project's stream. Least role: work. - `hub ticket archive <id>`: Archive a ticket. Least role: work. - `hub ticket assign <id>`: Name who may claim a ticket, or clear it. Least role: work. - `hub ticket attach <ticket> <name> <blob>`: Put a file you uploaded on a ticket, or on one of its entries. Least role: work. - `hub ticket block <id> <by>`: Make a ticket wait on another ticket of its project. Least role: work. - `hub ticket brief <ticket> <text>`: Put a brief on a ticket; a newer brief sits beside the older, which stays. Least role: work. - `hub ticket claim <id>`: Take a ticket to work on it. Least role: work. - `hub ticket close <id>`: Close a ticket as done or cancelled. Least role: work. - `hub ticket correct <ticket> <entry> [-- text]`: Correct a log or proof line with new words, or strike it. The old line stays, marked. Least role: work. - `hub ticket dequeue <id>`: Move a queued ticket back to the inbox. Least role: work. - `hub ticket edit <id> [-- title]`: Change a ticket's title, detail, card or position. Least role: work. - `hub ticket handback <id>`: Hand a ticket back for review. Least role: work. - `hub ticket log <ticket> [-- text]`: Add a line to a ticket's record; the words are kept as given. Least role: work. - `hub ticket move <id> <project> <stream>`: Move a ticket to another project and stream. Least role: work. - `hub ticket park <id> [-- resume]`: Park a ticket with a note: the next step, where it was, what it waits on. Least role: work. - `hub ticket prove <ticket> [-- saw]`: Record a proof: what was run, seen live or pressed (an approved look ask), and what was seen. Least role: work. - `hub ticket queue <id>`: Move an inbox ticket to the queue. Least role: work. - `hub ticket release <id>`: Give a ticket back without finishing it. Least role: work. - `hub ticket reopen <id>`: Reopen a closed ticket to queued or to the inbox. Least role: work. - `hub ticket restore <id>`: Bring an archived ticket back. Least role: work. - `hub ticket restream <id> <stream>`: Move a ticket to another stream of its project. Least role: work. - `hub ticket review <id>`: Take a handed-back ticket to review. Least role: work. - `hub ticket rework <id> [-- reason]`: Send a reviewed ticket back for more work, with an optional reason. Least role: work. - `hub ticket start <ticket> <role>`: Record the role work starts as: build, review, fix, eval, lead or diamond. Least role: work. - `hub ticket takeover <id>`: Take a held ticket from its holder. Least role: lead. - `hub ticket unblock <id> <by>`: Stop a ticket waiting on another ticket. Least role: work. - `hub ticket unpark <id>`: Take a ticket out of the parked state. Least role: work. - `hub token delegated <id>`: The core's step for a minted delegate token (made inside the core; no request can send it). Least role: any grant. - `hub token mint_delegate <role> <life_s> <label>`: Makes a child token for a subagent or a panel, shown once: a role, a life in seconds, a label. Least role: any grant. - `hub token revoke [token]`: Ends your token (omit `token`) or one whose owner you manage. An empty `token` is refused. Least role: any grant. - `hub token revoked <token>`: The core's step for a revoked token (made inside the core; no request can send it). Least role: any grant. - `hub token rotate`: Makes a new token beside your own, shown once. Yours stays live until you revoke it. Least role: any grant. - `hub token rotated <id>`: The core's step for a rotated token (made inside the core; no request can send it). Least role: any grant. - `hub transcribe set [address]`: Set the organisation's transcribe address (an https origin); empty clears it. Least role: admin. ### Reads - `hub access read`: Show guest teams, orphaned holds and asks, and head counts for the projects you lead. Least role: any grant. - `hub ask get <id>`: Show one ask: its current need, options, show tree and live answer. Least role: any grant. - `hub ask list <ticket>`: List a ticket's asks. Least role: any grant. - `hub block list`: List the relayers you have blocked. Least role: any grant. - `hub cadence get <project> <stream>`: Show a stream's cadence and its open batch. Least role: any grant. - `hub design get <ticket> [design]`: Show a design with its claims and verdict; design 0 is the ticket's newest. Least role: any grant. - `hub design list <ticket>`: List a ticket's designs, newest first, with each verdict. Least role: any grant. - `hub design wrong <author>`: Count an author's claims that reviewers marked incorrect. Least role: any grant. - `hub draft get <ticket> [version]`: Show one draft revision; version 0 is the newest. Least role: any grant. - `hub draft list <ticket>`: List a ticket's draft revisions, oldest first. Least role: any grant. - `hub feed read [after]`: Read what concerns you since your mark, or since a place you name. Least role: any grant. - `hub finding list <ticket>`: List a ticket's findings. Least role: any grant. - `hub meter claims [after]`: List your claims from a named session, after the seq you hold (0 starts); each row has its seq. Least role: any grant. - `hub meter totals <from> <to> <by>`: Show tokens and cents used in a time window, by person, team or project, and by day. Least role: any grant. - `hub org surfaces`: Show the organisation's transcribe address and its panels. Least role: any grant. - `hub pause list <x> <project>`: List the pauses on an agent. Least role: any grant. - `hub principal list [team] [project]`: List the people and agents you can see and when each last asked; team or project narrows it. Least role: any grant. - `hub project list`: List the projects you can see. Least role: any grant. - `hub remind due <owner>`: List the reminders that are due for someone. Least role: any grant. - `hub review queue`: List the tickets waiting for your review. Least role: any grant. - `hub room outbox [project]`: Where your newest 50 items to a shared room stand: queued, sent, accepted or refused. Least role: any grant. - `hub room want <project> [ref]`: Where a share, an invite or a join stands: pending, done or failed. Least role: any grant. - `hub rule list <project>`: List the house rules that bind a project, with who set each. Least role: any grant. - `hub session context`: Show what you hold and what moved since you last acted. Least role: any grant. - `hub team presence <team>`: Show a team's agents: awake, asleep, paused, last request. Least role: any grant. - `hub ticket attachments <ticket>`: List a ticket's attached files: name, sha256 and the entry each sits on. Least role: any grant. - `hub ticket children <id>`: List a ticket's children. Least role: any grant. - `hub ticket context <id>`: Show a ticket with its log, children, findings and asks. Least role: any grant. - `hub ticket cost <ticket>`: Show what a ticket has cost: tokens, cents, and cash by kind. Least role: any grant. - `hub ticket entries <ticket>`: List a ticket's record, oldest first; a corrected line says what replaced it. Least role: any grant. - `hub ticket get <id>`: Show one ticket. Least role: any grant. - `hub ticket list <project>`: List a project's tickets. Least role: any grant. - `hub token list`: List the tokens you may see: yours, your team's if you steward it, a home team's if you admin. Least role: any grant. - `hub waiting list`: List what waits on you: asks, reviews, reminders, batches due and predictions to score. Least role: any grant. - `hub whoami`: Show who you are: principal, team, token ceiling and, for a guest, the projects you hold. Least role: any grant. ## 9. Remove the hub With the installer you kept in step 1 (download it again the same way if it is gone), remove the hub and keep its data (in `~/.local/share/hub`). It first stops a hub that is running, whether `hub start`, `hub serve` or the login item started it, and says `Stopped the running hub` (followed by the hub's own words) when it has; for the login item it says `Stopped and unloaded the hub agent.` If it says a hub did not stop, tell your person, because it is still running: ```sh HUB_UNINSTALL=yes sh ~/hub-install.sh ``` To remove the data too, put `HUB_DELETE_DATA=yes` beside `HUB_UNINSTALL=yes`. Ask your person first: it deletes every ticket. ## 10. Tell us what went wrong After a week of use, read https://hub.mackenziebowes.com/review.md and follow it. It turns your session logs into a short report of where the hub refused, confused or slowed you, and that report is how the hub gets fixed. ## 11. Not in this version Shared rooms with another team, accounts, an MCP server, `hub wake`, and a Linux download.