CLI Reference

CLI Reference · [User]

The library ships an embeddable command tree (cobra-based, with carapace shell completion). Two trees exist:

• The teamserver tree — full server + user management, with the client tree nested under a client subcommand.
• The teamclient tree — a smaller client-only set for binaries with no server code.

Examples below use the standalone teamserver / teamclient binary names. In a real tool myapp, every command is prefixed: myapp teamserver daemon, myapp teamserver client users, etc.

Every command below also carries a Long description and an Example block in --help, and running <app> teamserver guide prints a full operator walkthrough.

---

Persistent flags (both trees)

Flag	Short	Description
--verbosity	-v	Count flag (-vvv) to raise stdout log verbosity.
--log-format		Console log format: console (default), text, json. Completed.

---

teamserver tree

teamserver [command]

teamserver control
  client      Client-only teamserver commands (import configs, show users, etc)
  close       Close a listener and remove it from persistent ones if it's one
  daemon      Start the teamserver in daemon mode (blocking)
  listen      Start a teamserver listener (non-blocking)
  status      Show the status of the teamserver (listeners, configurations, health...)
  systemd     Print a systemd unit file for the application teamserver, with options

user management
  delete      Remove a user from the teamserver, and revoke all its current tokens
  export      Export a Certificate Authority file containing the teamserver users
  import      Import a certificate Authority file containing teamserver users
  user        Create a user for this teamserver and generate its client configuration file

listen — start a listener (non-blocking)

Starts a bind job for a registered handler stack. Prints the listener and, with --persistent, saves it so the daemon restarts it.

Flag	Short	Default	Description
--host	-H	""	Interface to bind to (completed with local interfaces).
--port	-P	31337	TCP listen port.
--listener	-l	""	Handler stack to use instead of the default (completed by Name()).
--persistent	-p	false	Persist the listener across restarts.

teamserver listen --host localhost --persistent
teamserver listen --host 172.10.0.10 --port 32333 --listener gRPC --persistent

close — stop a listener

Closes an active listener by ID (prefix match) and removes it from saved/persistent jobs. Takes one or more listener IDs (completed from running + saved listeners).

teamserver close 3f9ab21c

daemon — run blocking, serve everything

Blocking. Serves the main listener plus all persistent listeners until SIGTERM (Ctrl-C).

Flag	Short	Default	Description
--host	-l	-	Multiplayer listener host (falls back to config).
--port	-p	0	Multiplayer listener port (falls back to config).

teamserver daemon --host localhost --port 31337
teamserver daemon                         # use config defaults

status — show server state

Prints general info (home dir, port, database, config path), logging (level, root log, audit path), certificate files, and a listeners table (active + saved).

teamserver status

systemd — print a systemd unit

Renders a systemd service unit for running teamserver daemon.

Flag	Short	Default	Description
--binpath	-b	""	Path of the teamserver binary.
--user	-u	""	User the unit runs as (takes a value).
--save	-s	""	Directory/file to write to instead of stdout.
--host	-l	""	Listen host baked into the unit command line.
--port	-p	0	Listen port baked into the unit command line.

teamserver systemd
teamserver systemd --binpath /usr/local/bin/myapp --host localhost --port 31337
teamserver systemd --user myapp --save /etc/systemd/system/myapp.service

user — create a user + config file

Generates a user (token + client certificate) and writes its *.teamclient.cfg.

Flag	Short	Default	Description
--name	-n	""	User name (alphanumeric, _, -).
--host	-l	""	Listen host baked into the config.
--port	-p	0	Listen port (0 ⇒ server default).
--save	-s	""	Directory/file to save the config (default: CWD).
--system	-U	false	Use the current OS user and save into the client configs dir.

teamserver user --name Michael --host localhost
teamserver user --name Bob --host 10.0.0.5 --port 32333 --save ~/configs/
teamserver user --system

delete — remove a user

Deletes a user's cert/token and revokes all live sessions. One argument (completed with current user names).

teamserver delete Michael

import / export — users CA

import loads a users CA file (adds those users); export writes this server's users CA.

teamserver import ~/.other_app/teamserver/certs/other_app_user-ca-cert.teamserver.pem
teamserver export ~/myapp-users.teamserver.ca      # arg optional; defaults to CWD

---

teamclient tree

Nested at teamserver client ..., or the root of a client-only binary:

teamclient [command]

Available Commands:
  import      Import a teamserver client configuration file for <app>
  users       Display a table of teamserver users and their status
  version     Print teamserver client version

import — import a server config

Imports one or more *.teamclient.cfg files into the client configs directory.

Flag	Short	Default	Description
--default	-d	false	Mark this config as the default if none exists yet.

teamclient import ~/Michael_localhost.teamclient.cfg
teamclient import --default ~/Michael_localhost.teamclient.cfg

users — list users

Connects and prints a table of users with online status and last-seen.

teamclient users

version — client + server version

Connects and prints both the server and client build/version info.

teamclient version

---

Shell completion

The trees ship rich carapace completions (users, listener IDs and types, config files, interfaces, log formats). Generate/source them via the hidden carapace command:

source <(teamserver _carapace <shell>)   # bash, zsh, fish, powershell, ...

---

Typical sessions

Admin bring-up (server):

teamserver user --name Michael --host localhost
teamserver listen --host localhost --persistent
teamserver status
teamserver daemon --host localhost --port 31337

Operator (client):

teamclient import ~/Michael_localhost.teamclient.cfg
teamclient users
teamclient version

See Common Workflows for end-to-end scenarios.