Skip to Content

CLI

Used from the Terminal for rapid access to your Spaces

Installing

Download the PairSpaces CLI, pair, using the link for your Operating System.

Move the executable pair to a directory in your PATH, for example, /usr/local/bin on Linux/macOS or C:\Program Files\pair\ on Windows.

Note For Windows users, add the pair CLI to your path using:

> setx PATH "%PATH%;C:\Program Files\pair" /M

And then restart the Command.exe application to update its path.

Test everything is working using:


> pair version

0.5.4-release (Latest)

Verifying the PairSpaces CLI for Linux

For Linux users the PairSpaces CLI can be verified using cosign. First, install cosign:

> curl -LO https://github.com/sigstore/cosign/releases/latest/download/cosign-linux-amd64
> chmod +x cosign-linux-amd64
> sudo mv cosign-linux-amd64 /usr/local/bin/cosign

Next, download the checksums, signature, and secret key as follows:

> wget https://s3.us-east-1.amazonaws.com/downloads.pairspaces.com/cli/release/pair_checksums.txt
> wget https://s3.us-east-1.amazonaws.com/downloads.pairspaces.com/cli/release/pair_checksums.txt.pem
> wget https://s3.us-east-1.amazonaws.com/downloads.pairspaces.com/cli/release/pair_checksums.txt.sig

Verify the pair_checksums.txt file using cosign:

> cosign verify-blob --certificate pair_checksums.txt.pem --signature pair_checksums.txt.sig --certificate-oidc-issuer="https://token.actions.githubusercontent.com" --certificate-identity-regexp=".*" pair_checksums.txt
Verified OK

This should output Verified OK, confirming that pair_checksums.txt has not been altered. Calculate the checksum of the pair binary you downloaded for your system:

> sha256sum pair
28ff5fc03b52d211e3a0e8de203a88e14c95b9bc93233ef141672b2bdb634501

And find the matching checksum in pair_checksums.txt:

> cat pair_checkums.txt
28ff5fc03b52d211e3a0e8de203a88e14c95b9bc93233ef141672b2bdb634501  linux/amd64/pair
efa02d0d14e7be79c483fbfce223cde257171e7b55468c3ae83ae379e56a0cba  linux/arm64/pair

Verifying the PairSpaces CLI for macOS

For macOS users the PairSpaces CLI is signed and notarized by Apple, Inc. It should not produce any security notifications on your Mac.

Verifying the PairSpaces CLI for Windows

For Windows users the PairSpaces CLI is signed using Azure Trusted Signing, a service provided by Microsoft, Inc. It should not produce any security notifications on your Windows PC.

Updating

The PairSpaces CLI will indicate when it needs to be updated when you use it.


> pair spaces

This version of PairSpaces CLI is out of date. Please upgrade from https://docs.pairspaces.com.
...

To update the PairSpaces CLI visit Installing and download the latest version.

Signing In

After creating a PairSpaces account at https://pairspaces.com/auth/signin, you will be able to sign in to the PairSpaces CLI using any command, for example:


> pair spaces

You are signed out. Signing you in...

1. Go to the browser that just opened. If a browser window did not appear, navigate to https://pairspaces.com/device/verify.
2. Enter the user code M6R6I9IZ.
3. When your session is created, return to this prompt.

PairSpaces CLI will open your default browser at a web page and ask you to sign in. After signing in, you will be asked to paste the code shared from the CLI into the form in the browser window. This will automatically sign you into the PairSpaces CLI.

Spaces

You can list the Spaces you created using pair spaces. When you have no Spaces, this is the output from the PairSpaces CLI:


> pair spaces

You have no spaces. Create one at https://pairspaces.com/spaces.

After you create Spaces, the output from pair spaces will be similar to this:


> pair spaces

Space ID			        Name				        Shared with you	
-------------------------	-------------------------	----------------
677029e3e72826e42fe49fcb	Space One			        No		
67702b34e72826e42fe4a059	Space Two			        No		
-------------------------	-------------------------	----------------
 

Each Space is identifed by its own unique identifer, a Space ID, its name, and whether it's shared with you from someone else. The value for Shared With You is Noif you created the Space and Yes if someone else created it and added you as a user of their Space.

Space Keys

You access Spaces using the same Secure Shell (SSH) technology that you use for any other remote machine.

The PairSpaces CLI generates Keys when you run pair keys. This command downloads a new public and private keypair and copies them to the default location for SSH keys on your system. If you have an existing public and private keypair at that location, PairSpaces will copy them by adding .bak to their names.


> pair keys

Your private key is available from ~/.ssh/id_ecdsa and your previous key was moved to ~/.ssh/id_ecdsa.bak.

PairSpaces does not keep a copy of your public and private keypair.

You can read about Keys and how we use SSH technology to enable you and your team to work together from Keys.

Space Shell

You can access your Space by using pair space SPACE_ID, where SPACE_ID is the unique identifier listed when you run pair spaces.


> pair space 677029e3e72826e42fe49fcb

   ,     #_
   ~\_  ####_        Amazon Linux 2023
  ~~  \_#####\
  ~~     \###|
  ~~       \#/ ___   https://aws.amazon.com/linux/amazon-linux-2023
   ~~       V~' '->
    ~~~         /
      ~~._.   _/
         _/ _/
       _/m/'
Last login: Wed Jan 01 09:41:01 2025 from YOUR_IP_ADDRESS
[ec2-user@ip-SPACE_IP_ADDRESS ~]$ 

Sharing Spaces

The PairSpaces CLI allows you to share your space with someone who is not a team member. This ad-hoc sharing is useful for trying PairSpaces with others, but also when you need to work with someone outside of your normal team. To share your space in this way, use pair space SPACE_ID --share EMAIL_ADDRESS, where SPACE_ID is the unique identifier listed when you run pair spaces and EMAIL_ADDRESS is the address of the person you want to work with.


> pair space 677029e3e72826e42fe49fcb -s EMAIL_ADDRESS

Your Space is shared and we've sent an email to EMAIL_ADDRESS. You can guide them to install the PairSpaces CLI from https://docs.pairspaces.com/getting-started/setting-up.

With the PairSpaces CLI installed, they can run the following command to join your PairSpace:

% pair space 677029e3e72826e42fe49fcb

To unshare your PairSpace at any time run:

% pair space 677029e3e72826e42fe49fcb --unshare

Your collaborator will receive an email that explains to them how to install the PairSpaces CLI and how to join your Space. This ad-hoc sharing is available to one person and for one hour at a time.

To share your Spaces with more than one person and for as long as you want, see Sharing Spaces.

Joining Spaces

If you received an invitation to work with someone in their Space, you first download the PairSpaces CLI and use the command shared with you from the link you clicked in the invitation email.


> pair join f4bfdb4e3b952f0f4062aa3af0ee3216

Starting shell...

   ,     #_
   ~\_  ####_        Amazon Linux 2023
  ~~  \_#####\
  ~~     \###|
  ~~       \#/ ___   https://aws.amazon.com/linux/amazon-linux-2023
   ~~       V~' '->
    ~~~         /
      ~~._.   _/
         _/ _/
       _/m/'
Last login: Wed Jan 01 09:41:01 2025 from YOUR_IP_ADDRESS
[ec2-user@ip-IP_ADDRESS ~]$

When you want to rejoin the Space (within that one-hour window), you use a slightly different command. This command will be shared in the output after you exit the Space.


To access your space again, use 'pair join SPACE_ID' (up to one hour after your first access).