CLI Reference¶

finchctl is the command-line controller for Finch. It manages the remote Finch service and enrolled agents over SSH and gRPC.

Synopsis¶

finchctl [flags] command

Global flags¶

These flags apply to every command.

service - Manage the Finch service¶

finchctl service command

service deploy¶

Deploy the Finch service to a remote host over SSH. Installs Docker if absent, copies all service configuration, starts the stack, and sets up the mTLS trust for this client: generates an ECDSA P-256 CA and client certificate pair locally, uploads the CA certificate to the server for authentication, and saves the client certificate and private key to ~/.config/finch.json. The CA key is locally discarded after signing the client certificate.

finchctl service deploy [user@]host[:port] [flags]

Example

# Deploy with a given hostname and Let's Encrypt TLS certificate.
# Requires port 80 to be public open and a DNS record for the HTTP challenge.
finchctl service deploy \
  --service.host finch.example.com \
  --service.letsencrypt \
  --service.letsencrypt.email acme@finch.example.com \
  root@10.19.80.100

service register¶

Register an additional client with an already deployed service. Generates an ECDSA P-256 CA and client certificate pair locally, uploads the CA certificate to the server for authentication, and saves the client certificate and private key to ~/.config/finch.json. The CA key is locally discarded after signing. Each client gets its own CA slot on the server.

finchctl service register [user@]host[:port] [flags]

Example

finchctl service register root@10.19.80.100

service deregister¶

Remove this client's registration from a remote service. Deletes the client's CA certificate from the server immediately revoking this client's ability to connect and removes the stored credentials from ~/.config/finch.json.

finchctl service deregister [user@]host[:port] [flags]

Example

finchctl service deregister root@10.19.80.100

service info¶

Show detailed information about a registered service, including its Id, Hostname, creation datetime, and the running version (release tag and git commit hash).

finchctl service info service-name [flags]

Example

finchctl service info finch.example.com

service update¶

Update a running service on a remote host (copy configurations, pull new images, restart containers).

finchctl service update [user@]host[:port] [flags]

Example

finchctl service update root@10.19.80.100

service teardown¶

Stop and remove the Finch service stack from a remote host. Docker is left intact and must be removed manually if desired.

finchctl service teardown [user@]host[:port] [flags]

Example

finchctl service teardown root@10.19.80.100

service rotate-certificate¶

Rotate the mTLS certificates of this client. Issues new ECDSA P-256 certificates and uploads the new CA certificate to the server, replacing the old one. Other registered clients are unaffected.

finchctl service rotate-certificate [user@]host[:port] [flags]

Example

finchctl service rotate-certificate root@10.19.80.100

service rotate-secret¶

Rotate the JWT signing secret of a running service. All existing agent tokens are immediately invalidated and agents must be re-enrolled afterwards.

finchctl service rotate-secret [user@]host[:port] [flags]

Example

finchctl service rotate-secret root@10.19.80.100

service dashboard¶

Generate a short-lived dashboard access token and optionally open it in the browser.

finchctl service dashboard service-name [flags]

Example

# Open dashboard as admin for 1 hour
finchctl service dashboard finch.example.com \
  --permission.role admin \
  --permission.session-timeout 3600 \
  --web

agent - Manage Finch agents¶

finchctl agent command

agent register¶

Register a new agent with a Finch service. Creates the agent record and generates a 365-day JWT, saved to the generated agent configuration file.

finchctl agent register service-name [flags]

Example

finchctl agent register finch.example.com \
  --agent.hostname web-01 \
  --agent.logs.journal \
  --agent.logs.docker \
  --agent.metrics

agent config¶

Download the current agent configuration from the service to a local file (used to bootstrap or refresh the Alloy configuration or token on an agent host).

finchctl agent config service-name [flags]

Example

finchctl agent config \
  --agent.rid rid:... \
  --agent.config web-01.cfg \
  finch.example.com

agent deploy¶

Deploy the Alloy agent binary and configuration to a remote host over SSH.

finchctl agent deploy [user@]host[:port] [flags]

Example

finchctl agent deploy --agent.config finch-agent.cfg root@172.17.0.4

agent edit¶

Edit the configuration of an already registered agent. Flags mirror agent register except --agent.node which cannot be changed after registration.

finchctl agent edit service-name [flags]

Example

finchctl agent edit \
    --agent.rid rid:... \
    --agent.labels "env=prod,role=web" \
    finch.example.com

agent list¶

List all agents registered with a service.

finchctl agent list service-name [flags]

Example

finchctl agent list 10.19.80.100

agent describe¶

Show detailed information about a specific agent.

finchctl agent describe service-name [flags]

Example

finchctl agent describe --agent.rid rid:... finch.example.com

agent deregister¶

Remove an agent from the service. Any agent's JWT is immediately invalidated.

finchctl agent deregister service-name [flags]

Example

finchctl agent deregister --agent.rid rid:... finch.example.com

agent update¶

Update the Alloy binary and/or configuration on a remote agent host over SSH.

finchctl agent update [user@]host[:port] [flags]

Example

finchctl agent update \
  --agent.config finch-agent.cfg \
  --skip.binaries \
  root@172.17.0.4

agent teardown¶

Uninstall Alloy and remove its configuration from a remote host.

finchctl agent teardown [user@]host[:port] [flags]

Example

finchctl agent teardown root@172.17.0.4

version¶

Print the finchctl version.

finchctl version

completion¶

Generate shell autocompletion scripts. Supported shells: bash, fish, powershell, zsh.

finchctl completion [bash|fish|powershell|zsh]

Example - zsh

echo 'source <(finchctl completion zsh)' >> ~/.zshrc

Example - bash

echo 'source <(finchctl completion bash)' >> ~/.bashrc