Teamtype

https://teamtype.github.io/teamtype
Admin
Teamtype is a system for real-time, local-first collaboration on text files across code editors...
Tokens:15,027
Snippets:188
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Run Magic Wormhole Mailbox Server with uvx

Source: https://teamtype.github.io/teamtype/relays.html

Starts the Magic Wormhole relay server on port 4000 by default. Requires uv to be installed.

```bash
uvx --from twisted --with magic-wormhole-mailbox-server twist wormhole-mailbox
```

--------------------------------

### Start TeamType client

Source: https://teamtype.github.io/teamtype/editor-plugin-dev-guide.html

Starts the TeamType client in the same directory as the daemon. Connecting produces "Editor connected" in the daemon; killing it shows "Editor disconnected".

```bash
teamtype client
```

--------------------------------

### Start daemon with debug logging

Source: https://teamtype.github.io/teamtype/editor-plugin-dev-guide.html

Starts the TeamType daemon with debug logging enabled. Expect output like "Listening on UNIX socket: <dir>/.teamtype/socket".

```bash
RUST_LOG=teamtype=debug teamtype share playground
```

--------------------------------

### Start nvim on a file

Source: https://teamtype.github.io/teamtype/editor-plugin-dev-guide.html

Opens a file in nvim to generate editor events for inspection.

```bash
nvim playground/file
```

--------------------------------

### Run Iroh Relay in Dev Mode

Source: https://teamtype.github.io/teamtype/relays.html

Starts the Iroh relay on port 3340 by default. Requires cargo install iroh-relay@0.35.0 --features=server.

```bash
iroh-relay --dev
```

--------------------------------

### Start a Teamtype sharing session

Source: https://teamtype.github.io/teamtype/pair-programming.html

Starts a Teamtype collaboration session from the project directory. Prints initialization information including a join code like '3-exhausted-bananas' to share with another person.

```bash
teamtype share
```

--------------------------------

### Run Iroh DNS Server

Source: https://teamtype.github.io/teamtype/relays.html

Starts the Iroh Pkarr relay on port 8080 and a DNS server on port 5300, resolving subdomains of irohdns.example. Requires cargo install iroh-dns-server@0.35.0.

```bash
iroh-dns-server
```

--------------------------------

### Teamtype share command with --directory parameter

Source: https://teamtype.github.io/teamtype/system-overview.html

Starts a Teamtype daemon for a project. If the --directory parameter is omitted, the current directory is used.

```bash
teamtype share --directory [DIRECTORY]
```

--------------------------------

### open

Source: https://teamtype.github.io/teamtype/print.html

Sent when the editor opens a document. The daemon responds with success or an error. On success, the editor gets ownership and receives updates.

```APIDOC
## open

### Description
Sent when the editor opens a document. The daemon will respond either with a success, or with an error describing why the file could not be opened (for example, because it is an ignored file, or if it’s not part of the daemons shared project). When an open succeeds, the editor gets ownership of the file, and the daemon will start sending updates for it as they come in.

### Method
JSON-RPC request

### Parameters
#### Request Body
- **uri** (DocumentUri) - Required - Absolute file URI of the document to open.
- **content** (String) - Required - The editor’s buffer content. If that content diverges from what the daemon thinks the content should be, it will send edits back.

### Notes
- The editor has to initialize its editor revision and daemon revision for that document to 0.
```

--------------------------------

### Create project directory on server

Source: https://teamtype.github.io/teamtype/print.html

Creates a new directory for the shared project on the server and changes into it. Run this on the server before launching the Teamtype daemon.

```bash
mkdir my-project
cd my-project
```

--------------------------------

### Create shared project directory on server

Source: https://teamtype.github.io/teamtype/shared-notes.html

Create a new directory for the shared project on the server, using `mkdir` and `cd` as shown.

```bash
__
mkdir my-project
cd my-project
```

--------------------------------

### Create a new file with nvim, touch, or cp

Source: https://teamtype.github.io/teamtype/file-events.html

Commands that create a new file in the project directory, which Teamtype syncs to connected peers. Use these while the daemon is running to record the changes.

```bash
nvim new_file
```

```bash
touch new_file
```

```bash
cp ../somewhere/else/file .
```

--------------------------------

### Connect to the cloud peer with teamtype join

Source: https://teamtype.github.io/teamtype/shared-notes.html

Once the secret address is configured, peers can connect to the cloud peer anytime using `teamtype join`.

```bash
teamtype join
```

--------------------------------

### Generate JSON-RPC open message

Source: https://teamtype.github.io/teamtype/editor-plugin-dev-guide.html

Runs the included Python script to generate a sample JSON-RPC open message for the given file.

```bash
python tools/dummy-jsonrpc.py playground/file
```

--------------------------------

### Peer workflow: fetch with git fetch

Source: https://teamtype.github.io/teamtype/git-integration-manual.html

Any other peer can fetch the changes without applying them. Teamtype already applies them to the working tree. Run `git fetch` to retrieve from the remote.

```bash
git fetch
```

--------------------------------

### Set Local DNS Server with resolvectl

Source: https://teamtype.github.io/teamtype/relays.html

Configures systemd-resolved to use the local DNS server for a network interface. Replace <interface> with your network interface name.

```bash
sudo resolvectl dns <interface> 127.0.0.1:5300
```

--------------------------------

### Set DNS Domain with resolvectl

Source: https://teamtype.github.io/teamtype/relays.html

Configures systemd-resolved to resolve only domains under irohdns.example using the local DNS server.

```bash
sudo resolvectl domain <interface> '~irohdns.example'
```

--------------------------------

### Join a Teamtype session with a join code

Source: https://teamtype.github.io/teamtype/pair-programming.html

Joins an existing Teamtype session using the join code provided by the host. On success, shows a message like 'Connected to peer: …' while the host daemon shows 'Peer connected: …'.

```bash
teamtype join 3-exhausted-bananas
```

--------------------------------

### Peer workflow: update HEAD with git reset @{u}

Source: https://teamtype.github.io/teamtype/git-integration-manual.html

After fetching, run `git reset @{u}` to move the current branch to the upstream commit and set the index to match, without touching the working directory. This brings all peers to the same Git state as the committer.

```bash
git reset @{u}
```

--------------------------------

### Convert binary file to hexdump with xxd

Source: https://teamtype.github.io/teamtype/print.html

Converts a binary file to a hexdump without color output, so it can be edited collaboratively as text.

```bash
xxd -R never binary_file > binary_file.hex
```

--------------------------------

### Listen on daemon socket with netcat

Source: https://teamtype.github.io/teamtype/editor-plugin-dev-guide.html

Removes any existing socket and listens on the daemon's UNIX socket to inspect raw incoming data. Requires the daemon to be stopped.

```bash
rm <dir>/.teamtype/socket; nc -lk -U <dir>/.teamtype/socket
```

--------------------------------

### Convert hexdump back to binary with xxd -r

Source: https://teamtype.github.io/teamtype/print.html

Converts the edited hexdump back to a binary file.

```bash
xxd -r binary_file.hex > binary_file
```

--------------------------------

### Launch Teamtype daemon with nohup

Source: https://teamtype.github.io/teamtype/shared-notes.html

Launch the Teamtype daemon in a way that keeps running after disconnecting from the terminal session. Using `nohup` writes output to `nohup.out` which contains the secret address. Other methods are `screen`, `tmux`, or a systemd service.

```bash
nohup teamtype share --show-secret-address &
```

--------------------------------

### Use custom Iroh Pkarr relay and DNS domain

Source: https://teamtype.github.io/teamtype/print.html

Instructs Teamtype to use a custom Pkarr relay and DNS domain for discovery. Alternatively, set the iroh_pkarr_relay and iroh_dns_domain parameters in .teamtype/config. It doesn't hurt to use both flags on both peers.

```bash
teamtype share --iroh-pkarr-relay http://localhost:8080/pkarr
```

```bash
teamtype join --iroh-dns-domain irohdns.example <join code>
```

--------------------------------

### Convert binary file to hexdump and back with xxd

Source: https://teamtype.github.io/teamtype/workarounds.html

Convert a binary file to a hexdump for collaborative editing, then convert the edited hexdump back to binary. The first command disables color output with -R never; the second restores the binary file.

```bash
xxd -R never binary_file > binary_file.hex
```

```bash
xxd -r binary_file.hex > binary_file
```

--------------------------------

### Teamtype configuration file options

Source: https://teamtype.github.io/teamtype/configuration.html

Configuration options for the Teamtype client, stored in `.teamtype/config`. After a successful `teamtype join`, the peer's secret address is automatically stored in this file, allowing future reconnects without a join code.

```plaintext
username = <string>
peer = <secret_address>

emit_join_code = <true/false>
emit_secret_address = <true/false>

magic_wormhole_relay = <magic_wormhole_mailbox_relay_url>
iroh_relay = <iroh_relay_url>
iroh_dns_domain = <iroh_dns_domain>
iroh_pkarr_relay = <iroh_pkarr_relay>
```

--------------------------------

### Add peer secret address to config

Source: https://teamtype.github.io/teamtype/shared-notes.html

Configure a peer by appending the secret address to the configuration file `.teamtype/config` using the `echo` command. Replace `<secret address>` with the actual address from the server.

```bash
echo "peer=<secret address>" >> .teamtype/config
```

--------------------------------

### Share with Magic Wormhole Relay

Source: https://teamtype.github.io/teamtype/relays.html

Shares a file using the specified Magic Wormhole relay. Use the same relay on the joining peer.

```bash
teamtype share --magic-wormhole-relay ws://localhost:4000/v1
```

--------------------------------

### cursor (editor to daemon)

Source: https://teamtype.github.io/teamtype/print.html

Sends current cursor position/selection(s). Replaces the previous cursor ranges.

```APIDOC
## cursor (editor to daemon)

### Description
Sends current cursor position/selection(s). Replaces the previous cursor ranges.

### Method
JSON-RPC request

### Parameters
#### Request Body
- **uri** (DocumentUri) - Required - Absolute file URI of the document.
- **ranges** (Range[]) - Required - The current cursor position/selection(s).
```

--------------------------------

### Join with Iroh DNS Domain

Source: https://teamtype.github.io/teamtype/relays.html

Joins a share using the specified Iroh DNS domain.

```bash
teamtype join --iroh-dns-domain irohdns.example <join code>
```

--------------------------------

### Modify an existing file with nvim, echo, sort, or git restore

Source: https://teamtype.github.io/teamtype/file-events.html

Commands that modify an existing file, either through a Teamtype-enabled editor or external tools. External changes are synced, but concurrent edits from an editor and an external tool may be lost.

```bash
nvim existing_file
```

```bash
echo new stuff >> file
```

```bash
sort -o file file
```

```bash
git restore file
```

--------------------------------

### Delete or move a file with rm or mv

Source: https://teamtype.github.io/teamtype/file-events.html

Commands that delete a file from the project or move it out of the project directory. These changes are synced to connected peers.

```bash
rm new_file
```

```bash
mv file ../somwhere/else/
```

--------------------------------

### Use custom Magic Wormhole relay with Teamtype

Source: https://teamtype.github.io/teamtype/print.html

Instructs Teamtype to use a custom Magic Wormhole relay for sharing and joining. Alternatively, set the magic_wormhole_relay parameter in .teamtype/config.

```bash
teamtype share --magic-wormhole-relay ws://localhost:4000/v1
```

```bash
teamtype join --magic-wormhole-relay ws://localhost:4000/v1 <join code>
```

--------------------------------

### Use custom Iroh relay with Teamtype

Source: https://teamtype.github.io/teamtype/print.html

Instructs Teamtype to use a custom Iroh relay for sharing and joining. Alternatively, set the iroh_relay parameter in .teamtype/config.

```bash
teamtype share --iroh-relay http://localhost:3340
```

```bash
teamtype join --iroh-relay http://localhost:3340 <join code>
```

--------------------------------

### Join with Magic Wormhole Relay

Source: https://teamtype.github.io/teamtype/relays.html

Joins a share using the specified Magic Wormhole relay and a join code.

```bash
teamtype join --magic-wormhole-relay ws://localhost:4000/v1 <join code>
```

--------------------------------

### Share with Iroh Relay

Source: https://teamtype.github.io/teamtype/relays.html

Shares a file using the specified Iroh relay.

```bash
teamtype share --iroh-relay http://localhost:3340
```

--------------------------------

### Send JSON-RPC message to daemon

Source: https://teamtype.github.io/teamtype/editor-plugin-dev-guide.html

Pipes the generated JSON-RPC message into the TeamType client to send it to the daemon.

```bash
python tools/dummy-jsonrpc.py playground/file | teamtype client
```

--------------------------------

### Share with Iroh Pkarr Relay

Source: https://teamtype.github.io/teamtype/relays.html

Shares a file using the specified Iroh Pkarr relay.

```bash
teamtype share --iroh-pkarr-relay http://localhost:8080/pkarr
```

--------------------------------

### cursor (daemon to editor)

Source: https://teamtype.github.io/teamtype/print.html

Sent by the daemon when user’s cursor positions or selections change, regardless of whether the file has been opened in the editor. The editor can use this information to display in which files other people work.

```APIDOC
## cursor (daemon to editor)

### Description
Sent by the daemon when user’s cursor positions or selections change, regardless of whether the file has been opened in the editor. The editor can use this information to display in which files other people work.

### Method
Notification (no reply needed)

### Parameters
#### Request Body
- **userid** (string) - Required - The user identifier.
- **name** (string) - Optional - The user's display name.
- **uri** (DocumentUri) - Required - Absolute file URI of the document.
- **ranges** (Range[]) - Required - The current cursor position/selection(s).
```

--------------------------------

### Teamtype component diagram

Source: https://teamtype.github.io/teamtype/print.html

Overview of the participating components in a Teamtype collaboration, showing daemons communicating over the internet, each with file system and editor, and editor with CRDT.

```plaintext
  daemon <---(Internet)---> daemon
  ^    ^                    ^    ^
  |    |                    |    |
  v    |                    v    |
 file  |                   file  |
system |                  system |
   ^   |                      ^  |
   |   |                      |  |
   v   v                       v  v
   editor  
```

--------------------------------

### Committer workflow: push with git push

Source: https://teamtype.github.io/teamtype/git-integration-manual.html

As the committer, after peers stop editing, create and push the commit to a remote repository. Executing `git push` in the terminal.

```bash
git push
```

--------------------------------

### Join with Iroh Relay

Source: https://teamtype.github.io/teamtype/relays.html

Joins a share using the specified Iroh relay and a join code.

```bash
teamtype join --iroh-relay http://localhost:3340 <join code>
```

--------------------------------

### edit (editor to daemon)

Source: https://teamtype.github.io/teamtype/print.html

Sent when the user edits an open document, or when the text editor makes a change to a text buffer content for any reason. The revision is the last revision seen from the daemon.

```APIDOC
## edit (editor to daemon)

### Description
Sent when the user edits an open document, or when the text editor makes a change to a text buffer content for any reason. The revision is the last revision seen from the daemon, meaning this edit is intended for that daemon revision.

### Method
JSON-RPC request

### Parameters
#### Request Body
- **uri** (DocumentUri) - Required - Absolute file URI of the document being edited.
- **revision** (number) - Required - The last revision seen from the daemon.
- **delta** (Delta) - Required - A complex text manipulation, similar to LSP’s TextEdit[]. All ranges refer to the starting content and must never overlap.

### Notes
- After each user edit, the editor must increase its editor revision.
- Pitfall: Do not send these messages when incorporating a remote edit into the buffer content. Filter out edits caused by the plugin.
```

--------------------------------

### edit (daemon to editor)

Source: https://teamtype.github.io/teamtype/print.html

Sent by the daemon to deliver an edit to the editor. The revision is the last revision the daemon has seen from the editor. If the revision does not match the editor's stored editor revision, the editor must ignore the edit.

```APIDOC
## edit (daemon to editor)

### Description
Sent by the daemon to deliver an edit to the editor. The revision is the last revision the daemon has seen from the editor. If this is not the editor revision stored in the editor, the editor must ignore the edit. The daemon will send an updated version later.

### Method
Notification (no reply needed)

### Parameters
#### Request Body
- **uri** (DocumentUri) - Required - Absolute file URI of the document.
- **revision** (number) - Required - The last revision the daemon has seen from the editor.
- **delta** (Delta) - Required - A complex text manipulation, similar to LSP’s TextEdit[]. All ranges refer to the starting content and must never overlap.

### Notes
- After applying the received edit, the editor must increase its daemon revision.
```

--------------------------------

### close

Source: https://teamtype.github.io/teamtype/print.html

Sent when the editor closes the file. The editor is no longer interested in receiving updates.

```APIDOC
## close

### Description
Sent when the editor closes the file. It is no longer interested in receiving updates.

### Method
JSON-RPC request

### Parameters
#### Request Body
- **uri** (DocumentUri) - Required - Absolute file URI of the document to close.
```
Tokens:
Raw