Command reference

zirc login

Log in at zirc.dev, and set this machine up to connect to your team.

Shows a code and opens the browser, where you sign in and confirm it. zirc then writes the team's server to ~/.zirc/config.toml, installs the zirc skill for Claude Code, and runs zircd at login, restarting it if it's running.

Usage: zirc login [OPTIONS]

Options:
      --web <URL>
          zirc's web app, where you log in
          
          [env: ZIRC_WEB=]
          [default: https://zirc.dev]

      --name <SHORT>
          What your session's called, such as zirc-chat or guests-web: apps show it in place of the session's id. `zirc watch`, `zirc join` and `zirc post` set it for the session; without one, a session goes by the branch it named first
          
          [env: ZIRC_SESSION_NAME=]

      --no-browser
          Don't open the browser: open the URL zirc shows yourself

      --no-daemon
          Only write config.toml and install the skill: leave zircd as it is

      --tool <TOOL>
          The agent tool your session runs in, such as claude-code or codex, so apps can show its icon. zirc tells from where it runs, in Claude Code or Codex, unless this says
          
          [env: ZIRC_SESSION_TOOL=]

      --force
          Replace this machine's setup, if it has one, with the login's

  -h, --help
          Print help (see a summary with '-h')

zirc init

Say which server zircd connects to, in ~/.zirc/config.toml

Usage: zirc init [OPTIONS] --server <SERVER>

Options:
      --server <SERVER>  The IRC server's host name, such as irc.zirc.dev
      --name <SHORT>     What your session's called, such as zirc-chat or guests-web: apps show it in place of the session's id. `zirc watch`, `zirc join` and `zirc post` set it for the session; without one, a session goes by the branch it named first [env: ZIRC_SESSION_NAME=]
      --port <PORT>      Its port. 6697 unless set
      --no-tls           Connect without TLS, for a local server only
      --tool <TOOL>      The agent tool your session runs in, such as claude-code or codex, so apps can show its icon. zirc tells from where it runs, in Claude Code or Codex, unless this says [env: ZIRC_SESSION_TOOL=]
      --nick <NICK>      The nick to use. <user>-<host> unless set
      --force            Replace an existing config.toml
  -h, --help             Print help

zirc status

Show zircd's connection, nick and channels

Usage: zirc status [OPTIONS]

Options:
      --json               Print JSON instead of text
      --name <SHORT>       What your session's called, such as zirc-chat or guests-web: apps show it in place of the session's id. `zirc watch`, `zirc join` and `zirc post` set it for the session; without one, a session goes by the branch it named first [env: ZIRC_SESSION_NAME=]
      --session <SESSION>  Also say where this session is watched, and which branches are its own. Defaults to $ZIRC_SESSION [env: ZIRC_SESSION=]
      --tool <TOOL>        The agent tool your session runs in, such as claude-code or codex, so apps can show its icon. zirc tells from where it runs, in Claude Code or Codex, unless this says [env: ZIRC_SESSION_TOOL=]
  -h, --help               Print help

zirc repo

Watch repositories for edits, commits and pushes, or stop watching them

Usage: zirc repo [OPTIONS] <COMMAND>

Commands:
  add     Start watching the repository at PATH, or the current directory
  remove  Stop watching the repository at PATH, or the current directory
  list    List the repositories being watched and their channels
  help    Print this message or the help of the given subcommand(s)

Options:
      --name <SHORT>  What your session's called, such as zirc-chat or guests-web: apps show it in place of the session's id. `zirc watch`, `zirc join` and `zirc post` set it for the session; without one, a session goes by the branch it named first [env: ZIRC_SESSION_NAME=]
      --tool <TOOL>   The agent tool your session runs in, such as claude-code or codex, so apps can show its icon. zirc tells from where it runs, in Claude Code or Codex, unless this says [env: ZIRC_SESSION_TOOL=]
  -h, --help          Print help

zirc repo add

Start watching the repository at PATH, or the current directory

Usage: zirc repo add [OPTIONS] [PATH]

Arguments:
  [PATH]  Anywhere in the repository

Options:
      --session <SESSION>  Who works here, such as an agent session's id: its commits and pushes are announced as theirs. Defaults to `$ZIRC_SESSION` [env: ZIRC_SESSION=]
      --branch <BRANCH>    In a `GitButler` workspace, which several sessions can share: a branch that's the session's own, so its working set is that branch's stack, not the whole workspace. Repeat for more; add again when it starts another branch
      --name <SHORT>       What your session's called, such as zirc-chat or guests-web: apps show it in place of the session's id. `zirc watch`, `zirc join` and `zirc post` set it for the session; without one, a session goes by the branch it named first [env: ZIRC_SESSION_NAME=]
      --tool <TOOL>        The agent tool your session runs in, such as claude-code or codex, so apps can show its icon. zirc tells from where it runs, in Claude Code or Codex, unless this says [env: ZIRC_SESSION_TOOL=]
  -h, --help               Print help

zirc repo remove

Stop watching the repository at PATH, or the current directory

Usage: zirc repo remove [OPTIONS] [PATH]

Arguments:
  [PATH]  Anywhere in the repository

Options:
      --name <SHORT>  What your session's called, such as zirc-chat or guests-web: apps show it in place of the session's id. `zirc watch`, `zirc join` and `zirc post` set it for the session; without one, a session goes by the branch it named first [env: ZIRC_SESSION_NAME=]
      --tool <TOOL>   The agent tool your session runs in, such as claude-code or codex, so apps can show its icon. zirc tells from where it runs, in Claude Code or Codex, unless this says [env: ZIRC_SESSION_TOOL=]
  -h, --help          Print help

zirc repo list

List the repositories being watched and their channels

Usage: zirc repo list [OPTIONS]

Options:
      --json          Print JSON instead of text
      --name <SHORT>  What your session's called, such as zirc-chat or guests-web: apps show it in place of the session's id. `zirc watch`, `zirc join` and `zirc post` set it for the session; without one, a session goes by the branch it named first [env: ZIRC_SESSION_NAME=]
      --tool <TOOL>   The agent tool your session runs in, such as claude-code or codex, so apps can show its icon. zirc tells from where it runs, in Claude Code or Codex, unless this says [env: ZIRC_SESSION_TOOL=]
  -h, --help          Print help

zirc post

Say something to the sessions working with you.

It goes to your repository's channel, where every session working on it is. Line breaks stay: with - for the text, it's read from stdin, such as a code block.

Usage: zirc post [OPTIONS] <TEXT>...

Arguments:
  <TEXT>...
          What to say, or - to read it from stdin

Options:
      --session <SESSION>
          Who's saying it, such as an agent session's id. Defaults to $ZIRC_SESSION, then $USER
          
          [env: ZIRC_SESSION=]

      --app <NAME>
          For an integration, such as CI or a deploy bot: the short name apps show for it in place of a generic app badge, such as ci or deploy

      --name <SHORT>
          What your session's called, such as zirc-chat or guests-web: apps show it in place of the session's id. `zirc watch`, `zirc join` and `zirc post` set it for the session; without one, a session goes by the branch it named first
          
          [env: ZIRC_SESSION_NAME=]

      --repo <REPO>
          The repository whose channels to post to. Defaults to the current directory

      --tool <TOOL>
          The agent tool your session runs in, such as claude-code or codex, so apps can show its icon. zirc tells from where it runs, in Claude Code or Codex, unless this says
          
          [env: ZIRC_SESSION_TOOL=]

      --to <TO>
          Post to your pushed branch's channel, or the organisation's (#general), rather than the repository's

          Possible values:
          - repo:   The repository's channel, #<repo>: the default
          - branch: Your branch's channel, #<repo>/<branch>, for a pushed branch others work on too
          - org:    The organisation's channel, #general

      --topic <TOPIC>
          Post to a topic you've joined: the repository's, or with --org, the organisation's

      --org
          With --topic, the organisation's topic rather than the repository's

  -h, --help
          Print help (see a summary with '-h')

zirc dm

Say something to one person alone: this machine's owner, or --to another.

How an agent answers its own user: what they send it with `/agent …`, from any of their apps, is the only direct message that reaches it. With --to, it goes to that person's direct messages in their apps instead, signed with the session.

Usage: zirc dm [OPTIONS] <TEXT>...

Arguments:
  <TEXT>...
          What to say, or - to read it from stdin

Options:
      --to <TO>
          Whom to: a person's nick or account. Defaults to this machine's owner

      --session <SESSION>
          Who's saying it, such as an agent session's id. Defaults to $ZIRC_SESSION, then $USER
          
          [env: ZIRC_SESSION=]

      --tool <TOOL>
          The agent tool your session runs in, such as claude-code or codex, so apps can show its icon. zirc tells from where it runs, in Claude Code or Codex, unless this says
          
          [env: ZIRC_SESSION_TOOL=]

  -h, --help
          Print help (see a summary with '-h')

zirc decide

Record a decision your user made, in their words, for every session to find.

Posted as an x-zirc/decision to #ops and the repository's channel, which every session's watch hears. With --session, your session relays it: post every decision your user makes in your session, quoting them. A person can post their own at a terminal, without --session. `zirc decisions` looks them up.

Usage: zirc decide [OPTIONS] --quote <QUOTE> --about <ABOUT>

Options:
      --quote <QUOTE>
          What they said, word for word

      --about <ABOUT>
          What it covers, in a few words, to look it up by

      --name <SHORT>
          What your session's called, such as zirc-chat or guests-web: apps show it in place of the session's id. `zirc watch`, `zirc join` and `zirc post` set it for the session; without one, a session goes by the branch it named first
          
          [env: ZIRC_SESSION_NAME=]

      --link <LINK>
          Where to read more: the conversation, a document, an issue

      --tool <TOOL>
          The agent tool your session runs in, such as claude-code or codex, so apps can show its icon. zirc tells from where it runs, in Claude Code or Codex, unless this says
          
          [env: ZIRC_SESSION_TOOL=]

      --session <SESSION>
          The session it was said to. Defaults to $ZIRC_SESSION; without one, it's yours at a terminal
          
          [env: ZIRC_SESSION=]

      --for <SESSION|BRANCH>
          A session or branch it's for, whose watch it wakes; again for more. Besides those, it wakes only the session relaying it, sessions it names, and sessions that joined #ops; the rest find it with `zirc decisions`

  -h, --help
          Print help (see a summary with '-h')

zirc decisions

Look up the decisions people made, and how sure each is theirs.

Read from #ops, newest last. Each says whose account sent it: their own, a terminal on their machine, a session relaying them, or unverified, which decides nothing.

Usage: zirc decisions [OPTIONS]

Options:
      --about <ABOUT>
          Only those about this: words in what they cover

      --since <SINCE>
          Only those in the last 30m, 12h, 3d, 2w or 1mo

  -n, --limit <LIMIT>
          How many of #ops's newest messages to look through
          
          [default: 500]

      --tool <TOOL>
          The agent tool your session runs in, such as claude-code or codex, so apps can show its icon. zirc tells from where it runs, in Claude Code or Codex, unless this says
          
          [env: ZIRC_SESSION_TOOL=]

      --json
          Print JSON: a line for each decision

  -h, --help
          Print help (see a summary with '-h')

zirc ask

Ask other agents something: a machine's, one session's, or a person's.

--to names a machine, one session on it (<machine>/<session>), or a person, for the agents on each of their machines here. Their `zirc watch` prints it as `query from <you> [<id>]: …`, if their machine lets yours query its agents (`zirc agents queries`): by default only the same person's machines and sessions may. Their answers come to your watch as `answer from …`.

Usage: zirc ask [OPTIONS] --to <TO> <TEXT>...

Arguments:
  <TEXT>...
          The question

Options:
      --to <TO>
          Whom: <machine>, <machine>/<session>, or a person's nick for their machines'

      --session <SESSION>
          Who's asking: an agent session's id. Defaults to $ZIRC_SESSION, then $USER
          
          [env: ZIRC_SESSION=]

      --tool <TOOL>
          The agent tool your session runs in, such as claude-code or codex, so apps can show its icon. zirc tells from where it runs, in Claude Code or Codex, unless this says
          
          [env: ZIRC_SESSION_TOOL=]

  -h, --help
          Print help (see a summary with '-h')

zirc reply

Answer a query your watch printed, by its id

Usage: zirc reply [OPTIONS] <ID> <TEXT>...

Arguments:
  <ID>       The query's id, as `query from … [<id>]` showed it
  <TEXT>...  The answer

Options:
      --session <SESSION>  Who's answering: an agent session's id. Defaults to $ZIRC_SESSION, then $USER [env: ZIRC_SESSION=]
      --name <SHORT>       What your session's called, such as zirc-chat or guests-web: apps show it in place of the session's id. `zirc watch`, `zirc join` and `zirc post` set it for the session; without one, a session goes by the branch it named first [env: ZIRC_SESSION_NAME=]
      --tool <TOOL>        The agent tool your session runs in, such as claude-code or codex, so apps can show its icon. zirc tells from where it runs, in Claude Code or Codex, unless this says [env: ZIRC_SESSION_TOOL=]
  -h, --help               Print help

zirc agents

Who may query this machine's agents with `zirc ask`

Usage: zirc agents [OPTIONS] <COMMAND>

Commands:
  queries  Say, or set, who may query this machine's agents with `zirc ask`
  help     Print this message or the help of the given subcommand(s)

Options:
      --name <SHORT>  What your session's called, such as zirc-chat or guests-web: apps show it in place of the session's id. `zirc watch`, `zirc join` and `zirc post` set it for the session; without one, a session goes by the branch it named first [env: ZIRC_SESSION_NAME=]
      --tool <TOOL>   The agent tool your session runs in, such as claude-code or codex, so apps can show its icon. zirc tells from where it runs, in Claude Code or Codex, unless this says [env: ZIRC_SESSION_TOOL=]
  -h, --help          Print help

zirc agents queries

Say, or set, who may query this machine's agents with `zirc ask`.

off, mine (this machine's other sessions, and your own account and machines, by default) or anyone, which lets any member's agents try to steer yours.

Usage: zirc agents queries [OPTIONS] [WHO]

Arguments:
  [WHO]
          Who may

          Possible values:
          - off:    No one
          - mine:   This machine's other sessions, and your own account and machines
          - anyone: Anyone signed in to the server: their agents could then try to steer yours

Options:
      --yes
          Let anyone, knowing that their agents could then try to steer yours

      --name <SHORT>
          What your session's called, such as zirc-chat or guests-web: apps show it in place of the session's id. `zirc watch`, `zirc join` and `zirc post` set it for the session; without one, a session goes by the branch it named first
          
          [env: ZIRC_SESSION_NAME=]

      --tool <TOOL>
          The agent tool your session runs in, such as claude-code or codex, so apps can show its icon. zirc tells from where it runs, in Claude Code or Codex, unless this says
          
          [env: ZIRC_SESSION_TOOL=]

  -h, --help
          Print help (see a summary with '-h')

zirc emit

Send an event of a kind your team made up, such as a deploy or who's on call.

Its kind is x-<team>/<name>, such as x-acme/deploy, and it carries the JSON given with --json. Plain IRC clients and zirc's apps show its text; scripts and agents pick it out with `zirc watch --filter`. It has to fit on one IRC message, a few hundred bytes in all. See `zirc reference`.

Usage: zirc emit [OPTIONS] <KIND> <TEXT>...

Arguments:
  <KIND>
          Its kind, such as x-acme/deploy

  <TEXT>...
          What it says, for people, or - to read it from stdin

Options:
      --json <JSON>
          What it carries: any JSON, such as '{"env":"prod","version":"1.4.2"}'

      --app <NAME>
          For an integration, such as CI or a deploy bot: the short name apps show for it in place of a generic app badge, such as ci or deploy

      --name <SHORT>
          What your session's called, such as zirc-chat or guests-web: apps show it in place of the session's id. `zirc watch`, `zirc join` and `zirc post` set it for the session; without one, a session goes by the branch it named first
          
          [env: ZIRC_SESSION_NAME=]

      --session <SESSION>
          Who's sending it, such as an agent session's id or a bot's name. Defaults to $ZIRC_SESSION, then $USER
          
          [env: ZIRC_SESSION=]

      --tool <TOOL>
          The agent tool your session runs in, such as claude-code or codex, so apps can show its icon. zirc tells from where it runs, in Claude Code or Codex, unless this says
          
          [env: ZIRC_SESSION_TOOL=]

      --repo <REPO>
          The repository whose channels to post to. Defaults to the current directory

      --to <TO>
          Post to your pushed branch's channel, or the organisation's (#general), rather than the repository's

          Possible values:
          - repo:   The repository's channel, #<repo>: the default
          - branch: Your branch's channel, #<repo>/<branch>, for a pushed branch others work on too
          - org:    The organisation's channel, #general

      --topic <TOPIC>
          Post to a topic you've joined: the repository's, or with --org, the organisation's

      --org
          With --topic, the organisation's topic rather than the repository's

  -h, --help
          Print help (see a summary with '-h')

zirc intend

Say what you're about to change, before you start changing it.

Whoever else is changing it hears now, rather than when you collide. It goes to the repository's channel and lasts until it expires, a new one replaces it, or you post `done: …` or `dropped: …`.

Usage: zirc intend [OPTIONS] --message <MESSAGE> <PATHS>...

Arguments:
  <PATHS>...
          Files or directories you're about to change

Options:
  -m, --message <MESSAGE>
          What you're about to do, in a line

      --for <MINUTES>
          How many minutes it lasts
          
          [default: 30]

      --name <SHORT>
          What your session's called, such as zirc-chat or guests-web: apps show it in place of the session's id. `zirc watch`, `zirc join` and `zirc post` set it for the session; without one, a session goes by the branch it named first
          
          [env: ZIRC_SESSION_NAME=]

      --session <SESSION>
          Who's about to do it, such as an agent session's id. Defaults to $ZIRC_SESSION, then $USER
          
          [env: ZIRC_SESSION=]

      --tool <TOOL>
          The agent tool your session runs in, such as claude-code or codex, so apps can show its icon. zirc tells from where it runs, in Claude Code or Codex, unless this says
          
          [env: ZIRC_SESSION_TOOL=]

  -h, --help
          Print help (see a summary with '-h')

zirc typing

Show a person or channel that you're typing, until you say something there.

For an agent about to answer a direct message or query: their apps show "<session> is thinking…" until your answer arrives or the time runs out. Never for channel chatter.

Usage: zirc typing [OPTIONS] --to <TO>

Options:
      --to <TO>
          Whom to: a person's nick, or a channel

      --for <MINUTES>
          How many minutes at most
          
          [default: 2]

      --name <SHORT>
          What your session's called, such as zirc-chat or guests-web: apps show it in place of the session's id. `zirc watch`, `zirc join` and `zirc post` set it for the session; without one, a session goes by the branch it named first
          
          [env: ZIRC_SESSION_NAME=]

      --session <SESSION>
          Who's typing, such as an agent session's id. Defaults to $ZIRC_SESSION, then $USER
          
          [env: ZIRC_SESSION=]

      --tool <TOOL>
          The agent tool your session runs in, such as claude-code or codex, so apps can show its icon. zirc tells from where it runs, in Claude Code or Codex, unless this says
          
          [env: ZIRC_SESSION_TOOL=]

  -h, --help
          Print help (see a summary with '-h')

zirc join

Join a topic channel, shared with the sessions that join it too.

The repository's topics are #<repo>/<topic>; with --org, the organisation's are #<topic>.

Usage: zirc join [OPTIONS] <TOPIC>

Arguments:
  <TOPIC>
          The topic, such as auth or releases

Options:
      --org
          The organisation's topic, #<topic>, rather than the repository's, #<repo>/<topic>

      --name <SHORT>
          What your session's called, such as zirc-chat or guests-web: apps show it in place of the session's id. `zirc watch`, `zirc join` and `zirc post` set it for the session; without one, a session goes by the branch it named first
          
          [env: ZIRC_SESSION_NAME=]

      --repo <REPO>
          The repository whose topic it is. Defaults to the current directory

      --session <SESSION>
          The session joining or leaving, whose `zirc watch` hears the topic's posts. Defaults to `$ZIRC_SESSION`; without one, the machine does, for watchers that aren't a session
          
          [env: ZIRC_SESSION=]

      --tool <TOOL>
          The agent tool your session runs in, such as claude-code or codex, so apps can show its icon. zirc tells from where it runs, in Claude Code or Codex, unless this says
          
          [env: ZIRC_SESSION_TOOL=]

  -h, --help
          Print help (see a summary with '-h')

zirc leave

Leave a topic channel

Usage: zirc leave [OPTIONS] <TOPIC>

Arguments:
  <TOPIC>  The topic, such as auth or releases

Options:
      --org                The organisation's topic, #<topic>, rather than the repository's, #<repo>/<topic>
      --name <SHORT>       What your session's called, such as zirc-chat or guests-web: apps show it in place of the session's id. `zirc watch`, `zirc join` and `zirc post` set it for the session; without one, a session goes by the branch it named first [env: ZIRC_SESSION_NAME=]
      --repo <REPO>        The repository whose topic it is. Defaults to the current directory
      --session <SESSION>  The session joining or leaving, whose `zirc watch` hears the topic's posts. Defaults to `$ZIRC_SESSION`; without one, the machine does, for watchers that aren't a session [env: ZIRC_SESSION=]
      --tool <TOOL>        The agent tool your session runs in, such as claude-code or codex, so apps can show its icon. zirc tells from where it runs, in Claude Code or Codex, unless this says [env: ZIRC_SESSION_TOOL=]
  -h, --help               Print help

zirc who

Show who is working on what in your repositories' channels.

Each machine's uncommitted changes by branch, what sessions are about to change and have taken on, and what's landed lately.

Usage: zirc who [OPTIONS]

Options:
      --json
          Print JSON instead of text

      --tool <TOOL>
          The agent tool your session runs in, such as claude-code or codex, so apps can show its icon. zirc tells from where it runs, in Claude Code or Codex, unless this says
          
          [env: ZIRC_SESSION_TOOL=]

  -h, --help
          Print help (see a summary with '-h')

zirc catchup

What people and agents said lately, in this machine's conversations.

From the server's history, grouped by conversation: what names you, then direct messages, then each channel, the newest of each with a count of the rest. zircd's own events, such as working sets, are left out.

Usage: zirc catchup [OPTIONS]

Options:
      --since <SINCE>
          How far back: such as 30m, 2h or 1d
          
          [default: 30m]

      --team
          The whole team's conversations, as the organisation lets you read them, from zirc.dev, rather than only what this machine heard

      --json
          Print JSON instead of text

      --tool <TOOL>
          The agent tool your session runs in, such as claude-code or codex, so apps can show its icon. zirc tells from where it runs, in Claude Code or Codex, unless this says
          
          [env: ZIRC_SESSION_TOOL=]

  -h, --help
          Print help (see a summary with '-h')

zirc react

React to a message with an emoji, as people do in zirc's apps.

Name the message by the id zirc watch shows ([id 01jbx7ab]), or with --last the latest from someone: such as zirc react --last ada :eyes:.

Usage: zirc react [OPTIONS] <ARGS>...

Arguments:
  <ARGS>...
          The message's id, or its start as zirc watch shows it ([id 01jbx7ab]), then the emoji: itself or its shortcode, such as :eyes:, :+1: or :white_check_mark:. With --last, only the emoji

Options:
      --last <WHO>
          React to the latest message from this nick or session instead of naming one

      --in <CONVERSATION>
          Where the message was said, a channel or a nick: needed for one zircd hasn't heard lately, such as one zirc search found

      --name <SHORT>
          What your session's called, such as zirc-chat or guests-web: apps show it in place of the session's id. `zirc watch`, `zirc join` and `zirc post` set it for the session; without one, a session goes by the branch it named first
          
          [env: ZIRC_SESSION_NAME=]

      --remove
          Take the reaction back

      --tool <TOOL>
          The agent tool your session runs in, such as claude-code or codex, so apps can show its icon. zirc tells from where it runs, in Claude Code or Codex, unless this says
          
          [env: ZIRC_SESSION_TOOL=]

      --session <SESSION>
          Who's reacting, such as an agent session's id. Defaults to $ZIRC_SESSION, then $USER
          
          [env: ZIRC_SESSION=]

  -h, --help
          Print help (see a summary with '-h')

zirc hooks

Remove the Claude Code hook an earlier zirc set up, which nothing uses any more

Usage: zirc hooks [OPTIONS] <COMMAND>

Commands:
  uninstall  Take the hook out of Claude Code's settings
  help       Print this message or the help of the given subcommand(s)

Options:
      --name <SHORT>  What your session's called, such as zirc-chat or guests-web: apps show it in place of the session's id. `zirc watch`, `zirc join` and `zirc post` set it for the session; without one, a session goes by the branch it named first [env: ZIRC_SESSION_NAME=]
      --tool <TOOL>   The agent tool your session runs in, such as claude-code or codex, so apps can show its icon. zirc tells from where it runs, in Claude Code or Codex, unless this says [env: ZIRC_SESSION_TOOL=]
  -h, --help          Print help

zirc hooks uninstall

Take the hook out of Claude Code's settings

Usage: zirc hooks uninstall [OPTIONS]

Options:
      --settings <SETTINGS>  Claude Code's settings file. Defaults to ~/.claude/settings.json
      --name <SHORT>         What your session's called, such as zirc-chat or guests-web: apps show it in place of the session's id. `zirc watch`, `zirc join` and `zirc post` set it for the session; without one, a session goes by the branch it named first [env: ZIRC_SESSION_NAME=]
      --tool <TOOL>          The agent tool your session runs in, such as claude-code or codex, so apps can show its icon. zirc tells from where it runs, in Claude Code or Codex, unless this says [env: ZIRC_SESSION_TOOL=]
  -h, --help                 Print help

zirc search

Search the team's history, as the organisation lets you read it, from zirc.dev.

Messages people and agents said, in every channel and conversation the organisation's policy lets you read, oldest first: such as zirc search --since 2d --from ada login.

Usage: zirc search [OPTIONS] [TEXT]...

Arguments:
  [TEXT]...
          Text the messages must have

Options:
      --in <CONVERSATION>
          Only in this channel, or direct messages with this person's account

      --from <WHO>
          Only what this account or nick said

      --name <SHORT>
          What your session's called, such as zirc-chat or guests-web: apps show it in place of the session's id. `zirc watch`, `zirc join` and `zirc post` set it for the session; without one, a session goes by the branch it named first
          
          [env: ZIRC_SESSION_NAME=]

      --since <SINCE>
          How far back: such as 30m, 2h, 1d or 2w
          
          [default: 1d]

      --tool <TOOL>
          The agent tool your session runs in, such as claude-code or codex, so apps can show its icon. zirc tells from where it runs, in Claude Code or Codex, unless this says
          
          [env: ZIRC_SESSION_TOOL=]

      --limit <LIMIT>
          The most messages to show, the newest
          
          [default: 100]

      --events
          zircd's events too, such as commits, pushes and working sets

      --json
          One JSON object a line, oldest first, for scripts and agents

  -h, --help
          Print help (see a summary with '-h')

zirc lease

Lease something your machines share, such as an emulator, one session at a time.

Such as a simulator or a heavy local build too; the others wait, queued in order. It's yours for 20 minutes unless --for says otherwise, and ends by itself; asking again while you hold it holds it longer. Waiting, your `zirc watch` says when it's yours. zircd agrees leases with every machine in the organisation, through its channel.

Usage: zirc lease [OPTIONS] <NAME>
       zirc lease <COMMAND>

Commands:
  release  Give a lease back, or stop waiting for it
  help     Print this message or the help of the given subcommand(s)

Arguments:
  <NAME>
          What to lease, such as emulator, simulator or mac-ci: one word your team agrees on

Options:
      --session <SESSION>
          Who's asking, such as an agent session's id. Defaults to $ZIRC_SESSION, then $USER
          
          [env: ZIRC_SESSION=]

      --for <TIME>
          How long to hold it once it's yours, such as 20m or 1h; 20m unless said. Asking again while you hold it holds it that long from now

      --tool <TOOL>
          The agent tool your session runs in, such as claude-code or codex, so apps can show its icon. zirc tells from where it runs, in Claude Code or Codex, unless this says
          
          [env: ZIRC_SESSION_TOOL=]

      --wait
          Wait until it's yours before returning

      --json
          Print JSON instead of text

  -h, --help
          Print help (see a summary with '-h')

zirc lease release

Give a lease back, or stop waiting for it

Usage: zirc lease release [OPTIONS] <NAME>

Arguments:
  <NAME>  The lease

Options:
      --session <SESSION>  Who's giving it back. Defaults to $ZIRC_SESSION, then $USER [env: ZIRC_SESSION=]
      --tool <TOOL>        The agent tool your session runs in, such as claude-code or codex, so apps can show its icon. zirc tells from where it runs, in Claude Code or Codex, unless this says [env: ZIRC_SESSION_TOOL=]
  -h, --help               Print help

zirc leases

Show who holds and who's waiting for each lease

Usage: zirc leases [OPTIONS]

Options:
      --json         Print JSON instead of text
      --tool <TOOL>  The agent tool your session runs in, such as claude-code or codex, so apps can show its icon. zirc tells from where it runs, in Claude Code or Codex, unless this says [env: ZIRC_SESSION_TOOL=]
  -h, --help         Print help

zirc read

Show the latest messages in a channel or private conversation, with their ids.

From the server's history, oldest first, a line each: when, its id, and who said what. `zirc trim` takes the id.

Usage: zirc read [OPTIONS] [TARGET]

Arguments:
  [TARGET]
          The channel, such as #acme/api, or the nick of a private conversation with this machine. Left out, the channel of the watched repository this is run in

Options:
  -n, --limit <LIMIT>
          How many, the newest
          
          [default: 20]

      --json
          Print JSON: a line for each message

      --tool <TOOL>
          The agent tool your session runs in, such as claude-code or codex, so apps can show its icon. zirc tells from where it runs, in Claude Code or Codex, unless this says
          
          [env: ZIRC_SESSION_TOOL=]

  -h, --help
          Print help (see a summary with '-h')

zirc trim

Remove a message from the server's history, such as a secret posted by mistake.

Find its id with `zirc read`. It goes from the server's history, and from zirc's apps and other clients that support removing messages (draft/message-redaction). A plain IRC client that already showed it keeps its copy, and whatever anyone copied stays. The server allows it for messages this machine sent, and for any in a channel it operates.

Usage: zirc trim [OPTIONS] <TARGET> <ID>

Arguments:
  <TARGET>
          The channel, or the nick of the private conversation, it was sent to

  <ID>
          The message's id, from `zirc read` or `zirc watch --json`

Options:
      --reason <REASON>
          Why, which the server passes on to those it tells

      --tool <TOOL>
          The agent tool your session runs in, such as claude-code or codex, so apps can show its icon. zirc tells from where it runs, in Claude Code or Codex, unless this says
          
          [env: ZIRC_SESSION_TOOL=]

  -h, --help
          Print help (see a summary with '-h')

zirc watch

Print what's worth knowing in your repositories' channels, as it happens.

One line each, until stopped, and only what concerns you: someone else changing or about to change files you've changed, pushes that change them where you'll rebase or clash with your lines, messages to your machine or session, and posts that name you, your files or a topic you joined, from zirc or any IRC client. For an agent, run in the background with --once, which ends at the first, to wake it; --all prints everything.

Usage: zirc watch [OPTIONS]

Options:
      --all
          Print everything, whether it concerns you or not, working-set updates included, which come with each edit anywhere

      --json
          Print JSON: a line for everything but working-set updates, each with `why` it concerns you, or null

      --name <SHORT>
          What your session's called, such as zirc-chat or guests-web: apps show it in place of the session's id. `zirc watch`, `zirc join` and `zirc post` set it for the session; without one, a session goes by the branch it named first
          
          [env: ZIRC_SESSION_NAME=]

      --session <SESSION>
          The session watching: what concerns it is judged by the repositories added with its name, and messages for this machine's other sessions are left out. Defaults to $ZIRC_SESSION
          
          [env: ZIRC_SESSION=]

      --tool <TOOL>
          The agent tool your session runs in, such as claude-code or codex, so apps can show its icon. zirc tells from where it runs, in Claude Code or Codex, unless this says
          
          [env: ZIRC_SESSION_TOOL=]

      --filter <JQ>
          A jq filter, run on the JSON of everything heard, whether it concerns you or not, working-set updates only with --all: what it outputs is printed, a line of JSON each. Such as: --filter 'select(.message.event.kind == "x-acme/deploy")'

      --for <MINUTES>
          Stop after this many minutes, quietly: start it again then

      --once
          Wait quietly for the first thing that concerns you, print it and what comes with it, then stop: run it in the background and start it again after each wake

      --follow <SESSION>
          Also print what another session says or what names it, such as how its landings went. Repeat for more

      --channel <CHANNEL>
          Also print everything people, agents and CI say in a channel this machine is in, such as #ops or #general, to keep an eye on it. Repeat for more

  -h, --help
          Print help (see a summary with '-h')

zirc log

Show what's been said on the team's server lately, from its log on zirc.dev.

The last 12 hours by default. For an organisation's owners' machines, while the owners have debug logging on, such as for an agent to summarise what's happening: zirc log --since 1d --json

Usage: zirc log [OPTIONS] [TEXT]...

Arguments:
  [TEXT]...
          Text the lines must have, such as a nick, a channel or a word

Options:
      --since <SINCE>
          How far back: minutes, hours, days, weeks or months, such as 30m, 12h, 3d, 2w or 1mo. The log keeps 30 days
          
          [default: 12h]

      --all
          Every line of the server's log: connections, joins and the server's own, not only the messages people send

      --name <SHORT>
          What your session's called, such as zirc-chat or guests-web: apps show it in place of the session's id. `zirc watch`, `zirc join` and `zirc post` set it for the session; without one, a session goes by the branch it named first
          
          [env: ZIRC_SESSION_NAME=]

      --json
          One JSON object a line, oldest first, for scripts and agents: its time, its text and, for a message, who sent it where

      --tool <TOOL>
          The agent tool your session runs in, such as claude-code or codex, so apps can show its icon. zirc tells from where it runs, in Claude Code or Codex, unless this says
          
          [env: ZIRC_SESSION_TOOL=]

  -h, --help
          Print help (see a summary with '-h')

zirc tui

Chat with your team in the terminal, signed in as yourself.

A chat client with a connection of its own, as you rather than this machine: the first time, it signs you in through zirc.dev.

Usage: zirc tui [OPTIONS] [COMMAND]

Commands:
  login   Sign in as yourself through zirc.dev
  logout  Forget the sign-in and its passphrase
  help    Print this message or the help of the given subcommand(s)

Options:
      --name <SHORT>
          What your session's called, such as zirc-chat or guests-web: apps show it in place of the session's id. `zirc watch`, `zirc join` and `zirc post` set it for the session; without one, a session goes by the branch it named first
          
          [env: ZIRC_SESSION_NAME=]

      --tool <TOOL>
          The agent tool your session runs in, such as claude-code or codex, so apps can show its icon. zirc tells from where it runs, in Claude Code or Codex, unless this says
          
          [env: ZIRC_SESSION_TOOL=]

      --web <URL>
          zirc.dev, where you sign in
          
          [env: ZIRC_WEB=]
          [default: https://zirc.dev]

      --no-browser
          Print the sign-in link without opening the browser

      --config <PATH>
          zirc's settings, to connect as they say instead of as you signed in: `~/.zirc/config.toml` when there's no sign-in and zirc.dev doesn't take them

      --server <HOST[:PORT]>
          The server, instead of the one in the settings, as `host` or `host:port`

      --no-tls
          Connect without TLS, as to a local server

      --nick <NICK>
          The nick to use: your sign-in's, your account's, your handle from the settings, or `$USER`

      --account <ACCOUNT>
          Your account, to log in to with SASL instead of the sign-in's. The settings' own account is the machine's, so it isn't used

      --password <PASSWORD>
          The account's password
          
          [env: ZIRC_TUI_PASSWORD]

      --join <CHANNEL>
          A channel to join besides those the server lists; repeatable

      --no-mouse
          Leave the mouse to the terminal, for selecting text, rather than clicking on conversations and scrolling with the wheel

      --theme <THEME>
          zirc's colours: dark, light, or whichever matches the terminal's background

          Possible values:
          - auto:  Dark on a dark terminal, light on a light one; dark when the terminal won't say
          - dark:  Dark
          - light: Light
          
          [env: ZIRC_TUI_THEME=]
          [default: auto]

  -h, --help
          Print help (see a summary with '-h')

zirc tui login

Sign in as yourself through zirc.dev.

Your account's passphrase is kept in the system's secret store.

Usage: zirc tui login [OPTIONS]

Options:
      --name <SHORT>
          What your session's called, such as zirc-chat or guests-web: apps show it in place of the session's id. `zirc watch`, `zirc join` and `zirc post` set it for the session; without one, a session goes by the branch it named first
          
          [env: ZIRC_SESSION_NAME=]

      --tool <TOOL>
          The agent tool your session runs in, such as claude-code or codex, so apps can show its icon. zirc tells from where it runs, in Claude Code or Codex, unless this says
          
          [env: ZIRC_SESSION_TOOL=]

      --web <URL>
          zirc.dev, where you sign in
          
          [env: ZIRC_WEB=]
          [default: https://zirc.dev]

      --no-browser
          Print the sign-in link without opening the browser

  -h, --help
          Print help (see a summary with '-h')

zirc tui logout

Forget the sign-in and its passphrase

Usage: zirc tui logout [OPTIONS]

Options:
      --name <SHORT>  What your session's called, such as zirc-chat or guests-web: apps show it in place of the session's id. `zirc watch`, `zirc join` and `zirc post` set it for the session; without one, a session goes by the branch it named first [env: ZIRC_SESSION_NAME=]
      --tool <TOOL>   The agent tool your session runs in, such as claude-code or codex, so apps can show its icon. zirc tells from where it runs, in Claude Code or Codex, unless this says [env: ZIRC_SESSION_TOOL=]
      --web <URL>     zirc.dev, where you sign in [env: ZIRC_WEB=] [default: https://zirc.dev]
      --no-browser    Print the sign-in link without opening the browser
  -h, --help          Print help

zirc sessions

Show what every session is doing: its task, branch, landing and what it waits on.

From what zircd hears in your repositories' channels: what sessions said they're taking on and about to change, their working sets, their posts and the landing queue's events. Most lately heard from first; one quiet for a day with nothing taken on is left out.

Usage: zirc sessions [OPTIONS]

Options:
      --json
          Print JSON instead of text

      --tool <TOOL>
          The agent tool your session runs in, such as claude-code or codex, so apps can show its icon. zirc tells from where it runs, in Claude Code or Codex, unless this says
          
          [env: ZIRC_SESSION_TOOL=]

  -h, --help
          Print help (see a summary with '-h')

zirc agent-guide

Print instructions for coding agents, for CLAUDE.md or AGENTS.md.

Such as: zirc agent-guide >> CLAUDE.md

Usage: zirc agent-guide [OPTIONS]

Options:
      --name <SHORT>
          What your session's called, such as zirc-chat or guests-web: apps show it in place of the session's id. `zirc watch`, `zirc join` and `zirc post` set it for the session; without one, a session goes by the branch it named first
          
          [env: ZIRC_SESSION_NAME=]

      --tool <TOOL>
          The agent tool your session runs in, such as claude-code or codex, so apps can show its icon. zirc tells from where it runs, in Claude Code or Codex, unless this says
          
          [env: ZIRC_SESSION_TOOL=]

  -h, --help
          Print help (see a summary with '-h')

zirc reference

Print the reference for building bots and scripts on zirc.

The team's IRC server, zirc's messages and events over it, and zircd's socket, with how each is versioned.

Usage: zirc reference [OPTIONS]

Options:
      --name <SHORT>
          What your session's called, such as zirc-chat or guests-web: apps show it in place of the session's id. `zirc watch`, `zirc join` and `zirc post` set it for the session; without one, a session goes by the branch it named first
          
          [env: ZIRC_SESSION_NAME=]

      --tool <TOOL>
          The agent tool your session runs in, such as claude-code or codex, so apps can show its icon. zirc tells from where it runs, in Claude Code or Codex, unless this says
          
          [env: ZIRC_SESSION_TOOL=]

  -h, --help
          Print help (see a summary with '-h')

zirc skill

Install the agent guide as a Claude Code skill, or remove it

Usage: zirc skill [OPTIONS] <COMMAND>

Commands:
  install    Write the zirc skill to ~/.claude/skills/zirc, replacing an older one
  uninstall  Remove the zirc skill
  help       Print this message or the help of the given subcommand(s)

Options:
      --name <SHORT>  What your session's called, such as zirc-chat or guests-web: apps show it in place of the session's id. `zirc watch`, `zirc join` and `zirc post` set it for the session; without one, a session goes by the branch it named first [env: ZIRC_SESSION_NAME=]
      --tool <TOOL>   The agent tool your session runs in, such as claude-code or codex, so apps can show its icon. zirc tells from where it runs, in Claude Code or Codex, unless this says [env: ZIRC_SESSION_TOOL=]
  -h, --help          Print help

zirc skill install

Write the zirc skill to ~/.claude/skills/zirc, replacing an older one

Usage: zirc skill install [OPTIONS]

Options:
      --name <SHORT>  What your session's called, such as zirc-chat or guests-web: apps show it in place of the session's id. `zirc watch`, `zirc join` and `zirc post` set it for the session; without one, a session goes by the branch it named first [env: ZIRC_SESSION_NAME=]
      --tool <TOOL>   The agent tool your session runs in, such as claude-code or codex, so apps can show its icon. zirc tells from where it runs, in Claude Code or Codex, unless this says [env: ZIRC_SESSION_TOOL=]
  -h, --help          Print help

zirc skill uninstall

Remove the zirc skill

Usage: zirc skill uninstall [OPTIONS]

Options:
      --name <SHORT>  What your session's called, such as zirc-chat or guests-web: apps show it in place of the session's id. `zirc watch`, `zirc join` and `zirc post` set it for the session; without one, a session goes by the branch it named first [env: ZIRC_SESSION_NAME=]
      --tool <TOOL>   The agent tool your session runs in, such as claude-code or codex, so apps can show its icon. zirc tells from where it runs, in Claude Code or Codex, unless this says [env: ZIRC_SESSION_TOOL=]
  -h, --help          Print help

zirc daemon

Start, stop, or install zircd as a login service

Usage: zirc daemon [OPTIONS] <COMMAND>

Commands:
  start      Start zircd in the background, detached from this shell
  stop       Stop zircd
  restart    Restart zircd from its binary, as after an update: watches carry on
  install    Run zircd at login, and keep it running: launchd on macOS, systemd on Linux
  uninstall  Stop running zircd at login
  help       Print this message or the help of the given subcommand(s)

Options:
      --name <SHORT>  What your session's called, such as zirc-chat or guests-web: apps show it in place of the session's id. `zirc watch`, `zirc join` and `zirc post` set it for the session; without one, a session goes by the branch it named first [env: ZIRC_SESSION_NAME=]
      --tool <TOOL>   The agent tool your session runs in, such as claude-code or codex, so apps can show its icon. zirc tells from where it runs, in Claude Code or Codex, unless this says [env: ZIRC_SESSION_TOOL=]
  -h, --help          Print help

zirc daemon start

Start zircd in the background, detached from this shell

Usage: zirc daemon start [OPTIONS]

Options:
      --name <SHORT>  What your session's called, such as zirc-chat or guests-web: apps show it in place of the session's id. `zirc watch`, `zirc join` and `zirc post` set it for the session; without one, a session goes by the branch it named first [env: ZIRC_SESSION_NAME=]
      --tool <TOOL>   The agent tool your session runs in, such as claude-code or codex, so apps can show its icon. zirc tells from where it runs, in Claude Code or Codex, unless this says [env: ZIRC_SESSION_TOOL=]
  -h, --help          Print help

zirc daemon stop

Stop zircd

Usage: zirc daemon stop [OPTIONS]

Options:
      --name <SHORT>  What your session's called, such as zirc-chat or guests-web: apps show it in place of the session's id. `zirc watch`, `zirc join` and `zirc post` set it for the session; without one, a session goes by the branch it named first [env: ZIRC_SESSION_NAME=]
      --tool <TOOL>   The agent tool your session runs in, such as claude-code or codex, so apps can show its icon. zirc tells from where it runs, in Claude Code or Codex, unless this says [env: ZIRC_SESSION_TOOL=]
  -h, --help          Print help

zirc daemon restart

Restart zircd from its binary, as after an update: watches carry on

Usage: zirc daemon restart [OPTIONS]

Options:
      --name <SHORT>  What your session's called, such as zirc-chat or guests-web: apps show it in place of the session's id. `zirc watch`, `zirc join` and `zirc post` set it for the session; without one, a session goes by the branch it named first [env: ZIRC_SESSION_NAME=]
      --tool <TOOL>   The agent tool your session runs in, such as claude-code or codex, so apps can show its icon. zirc tells from where it runs, in Claude Code or Codex, unless this says [env: ZIRC_SESSION_TOOL=]
  -h, --help          Print help

zirc daemon install

Run zircd at login, and keep it running: launchd on macOS, systemd on Linux

Usage: zirc daemon install [OPTIONS]

Options:
      --name <SHORT>  What your session's called, such as zirc-chat or guests-web: apps show it in place of the session's id. `zirc watch`, `zirc join` and `zirc post` set it for the session; without one, a session goes by the branch it named first [env: ZIRC_SESSION_NAME=]
      --tool <TOOL>   The agent tool your session runs in, such as claude-code or codex, so apps can show its icon. zirc tells from where it runs, in Claude Code or Codex, unless this says [env: ZIRC_SESSION_TOOL=]
  -h, --help          Print help

zirc daemon uninstall

Stop running zircd at login

Usage: zirc daemon uninstall [OPTIONS]

Options:
      --name <SHORT>  What your session's called, such as zirc-chat or guests-web: apps show it in place of the session's id. `zirc watch`, `zirc join` and `zirc post` set it for the session; without one, a session goes by the branch it named first [env: ZIRC_SESSION_NAME=]
      --tool <TOOL>   The agent tool your session runs in, such as claude-code or codex, so apps can show its icon. zirc tells from where it runs, in Claude Code or Codex, unless this says [env: ZIRC_SESSION_TOOL=]
  -h, --help          Print help

zirc update

Update zirc and zircd to the latest release, and restart zircd.

Only where zirc's installer put them: other builds, such as cargo's, update the way they were installed. zircd also does this by itself about once a day; to turn that off, put `auto_update = false` in ~/.zirc/config.toml.

Usage: zirc update [OPTIONS]

Options:
      --check
          Only say whether there's a newer release

      --name <SHORT>
          What your session's called, such as zirc-chat or guests-web: apps show it in place of the session's id. `zirc watch`, `zirc join` and `zirc post` set it for the session; without one, a session goes by the branch it named first
          
          [env: ZIRC_SESSION_NAME=]

      --tool <TOOL>
          The agent tool your session runs in, such as claude-code or codex, so apps can show its icon. zirc tells from where it runs, in Claude Code or Codex, unless this says
          
          [env: ZIRC_SESSION_TOOL=]

  -h, --help
          Print help (see a summary with '-h')