# CLI Usage

The Ringspace binary is an all-in-one tool for site and ring management. The top-level commands are:

```
Usage: ringspace <COMMAND>

Commands:
  ring     Manage a Ringspace Ring
  member   Manage Ring Members (as a Ring manager)
  site     Manage a Ringspace Sites (as a site owner)
  server   Launch the Ringspace Server
  invite   Manage Invites
  enckey   Generate an encryption keypair
  signkey  Generate a signing keypair
  migrate  Perform any necessary database migrations between versions
  help     Print this message or the help of the given subcommand(s)

Options:
  -h, --help  Print help
```

## Ring Commands

```
Manage a Ringspace Ring

Usage: ringspace ring
       ringspace ring create [OPTIONS]
       ringspace ring list
       ringspace ring get [OPTIONS]
       ringspace ring delete --ring-url <RING_URL>
       ringspace ring set-default --ring-url <RING_URL>
       ringspace ring decrypt-vote [OPTIONS] --encrypted-vote <ENCRYPTED_VOTE>
       ringspace ring manifest [OPTIONS]
       ringspace ring fetch-votes [OPTIONS]
       ringspace ring help [COMMAND]...

Options:
  -h, --help  Print help

ringspace ring create:
Create a new ring
  -n, --name <NAME>                Ring Name
  -r, --url <URL>                  Ring URL
  -d, --description <DESCRIPTION>  Ring Description
  -f, --default                    Set as default
  -h, --help                       Print help

ringspace ring list:
List rings
  -h, --help  Print help

ringspace ring get:
Get ring by URL
  -r, --ring-url <RING_URL>  Ring URL
  -h, --help                 Print help

ringspace ring delete:
Delete ring
  -r, --ring-url <RING_URL>  Ring URL
  -h, --help                 Print help

ringspace ring set-default:
Set default ring
  -r, --ring-url <RING_URL>  Ring URL
  -h, --help                 Print help

ringspace ring decrypt-vote:
Decrypt a single base64-encoded vote from a site
  -r, --ring-url <RING_URL>              Ring URL (default if omitted)
  -v, --encrypted-vote <ENCRYPTED_VOTE>  Base64-encoded encrypted vote
  -h, --help                             Print help

ringspace ring manifest:
Generate Ring Manifest
  -r, --ring-url <RING_URL>  Ring URL (default if omitted)
  -h, --help                 Print help

ringspace ring fetch-votes:
Fetch Ring votes
  -r, --ring-url <RING_URL>  Ring URL (default if omitted)
  -h, --help                 Print help

ringspace ring help:
Print this message or the help of the given subcommand(s)
  [COMMAND]...  Print help for the subcommand(s)
```


## Site Commands

```
Manage a Ringspace Site (as a site owner)

Usage: ringspace site
       ringspace site list
       ringspace site create [OPTIONS]
       ringspace site get [OPTIONS]
       ringspace site delete --site-url <SITE_URL>
       ringspace site join-ring [OPTIONS] --ring-url <RING_URL> --invite-code <INVITE_CODE>
       ringspace site leave-ring [OPTIONS] --ring-url <RING_URL>
       ringspace site manifest [OPTIONS]
       ringspace site rotate [OPTIONS]
       ringspace site set-default --url <SITE_URL>
       ringspace site vote [OPTIONS] --vote-subject <VOTE_SUBJECT> --description <DESCRIPTION>
       ringspace site vote-wizard [OPTIONS]
       ringspace site help [COMMAND]...

Options:
  -h, --help  Print help

ringspace site list:
List Sites
  -h, --help  Print help

ringspace site create:
Add Site
  -n, --name <NAME>                Site Name
  -u, --url <URL>                  Member Url
  -d, --description <DESCRIPTION>  Site Description
  -f, --default                    Set as default
  -h, --help                       Print help

ringspace site get:
Get Site by URL
  -u, --site-url <SITE_URL>  Site URL
  -h, --help                 Print help

ringspace site delete:
Remove Site
  -i, --site-url <SITE_URL>  Site URL
  -h, --help                 Print help

ringspace site join-ring:
Join Ring with Invite Code
  -u, --site-url <SITE_URL>        Site URL
  -r, --ring-url <RING_URL>        Ring URL
  -c, --invite-code <INVITE_CODE>  Invite Code
  -f, --default-ring               Set as default
  -h, --help                       Print help

ringspace site leave-ring:
Request unenrollment from a Ring
  -u, --site-url <SITE_URL>  Site URL
  -r, --ring-url <RING_URL>  Ring URL
  -h, --help                 Print help

ringspace site manifest:
Generate Site Manifest
  -u, --url <SITE_URL>  Site URL
  -h, --help            Print help

ringspace site rotate:
Rotate Site key
  -u, --url <SITE_URL>  Site URL
  -h, --help            Print help

ringspace site set-default:
Set Default Site
  -u, --url <SITE_URL>  Site URL
  -h, --help            Print help

ringspace site vote:
Add a Vote to a given ring/site
  -u, --url <URL>                    Site URL
  -r, --ring-url <RING_URL>          Ring URL
  -v, --vote-subject <VOTE_SUBJECT>  Vote Subject URL
  -s, --standing <STANDING>          Standing
  -d, --description <DESCRIPTION>    Description
  -h, --help                         Print help

ringspace site vote-wizard:
Run an interactive vote generator for all current Ring members
  -u, --url <SITE_URL>  Site URL
  -h, --help            Print help

ringspace site help:
Print this message or the help of the given subcommand(s)
  [COMMAND]...  Print help for the subcommand(s)
```

## Server Commands

```
Launch the Ringspace Server

Usage: ringspace server [OPTIONS]

Options:
  -p, --port <PORT>          Server port [default: 8000]
  -a, --address <ADDRESS>    Server address [default: 0.0.0.0]
  -r, --ring-url <RING_URL>  Ring URL
  -h, --help                 Print help```
```

> [!IMPORTANT]  
> Do not expose the Ringspace server directly to the internet. Use a reverse proxy like [Caddy](https://caddyserver.com) for resilience, rate-limiting, and more.

## Invite Commands

```
Manage Invites

Usage: ringspace invite
       ringspace invite create [OPTIONS] --url <URL>
       ringspace invite list
       ringspace invite revoke [OPTIONS] --id <INVITE_ID>
       ringspace invite help [COMMAND]...

Options:
  -h, --help  Print help

ringspace invite create:
Create a new invitation
  -u, --url <URL>                          Member URL
  -e, --expiration-hrs <EXPIRATION_HOURS>  Hours until code expires [default: 72]
  -r, --ring-url <RING_URL>                Ring URL
  -h, --help                               Print help

ringspace invite list:
List invitations
  -h, --help  Print help

ringspace invite revoke:
Revoke invitation by ID
  -i, --id <INVITE_ID>     Invitation ID
  -y, --confirm <CONFIRM>  Confirm [possible values: true, false]
  -h, --help               Print help

ringspace invite help:
Print this message or the help of the given subcommand(s)
  [COMMAND]...  Print help for the subcommand(s)
```
