Skip to content

CLI-REFERENCE.md

Latest commit

 

History

History
317 lines (219 loc) · 7.61 KB

CLI-REFERENCE.md

File metadata and controls

317 lines (219 loc) · 7.61 KB

CLI Reference

Name

certkit-agent - install, run, register, validate, lock, unlock, and uninstall the CertKit Agent.

Synopsis

certkit-agent install    [--key REGISTRATION_KEY] [--service-name NAME] [--config PATH]
certkit-agent uninstall  [--service-name NAME] [--config PATH]
certkit-agent run        [--key REGISTRATION_KEY] [--config PATH] [--once]
certkit-agent register   REGISTRATION_KEY [--config PATH]
certkit-agent validate   [--config PATH]
certkit-agent lock       [--config PATH]
certkit-agent unlock     [--config PATH]
certkit-agent version

Defaults

  • Service name: certkit-agent
  • Default config path (Linux): /etc/certkit-agent/config.json
  • Default config path (Windows): C:\ProgramData\CertKit\certkit-agent\config.json
  • --service-name and --config are optional and primarily for advanced/non-default deployments.

Command Reference

install

Synopsis

certkit-agent install [--key REGISTRATION_KEY] [--service-name NAME] [--config PATH]

Options

  • --key REGISTRATION_KEY
    • Registration key used only when a new config must be created.
  • --service-name NAME
    • Optional. Advanced setup for non-default service naming.
  • --config PATH
    • Optional. Advanced setup for non-default config path.

Behavior

  • Creates config if missing.
  • Installs/updates service configuration for the selected service name and config path.
  • Preserves existing config when already present.

Examples

# Linux default install
sudo certkit-agent install --key abc.xyz

# Linux custom service/config
sudo certkit-agent install --key abc.xyz --service-name edge-agent --config /opt/certkit/edge/config.json
# Windows (elevated) default install
certkit-agent.exe install --key abc.xyz

# Windows (elevated) custom service/config
certkit-agent.exe install --key abc.xyz --service-name edge-agent --config "C:\ProgramData\CertKit\edge\config.json"

uninstall

Synopsis

certkit-agent uninstall [--service-name NAME] [--config PATH]

Options

  • --service-name NAME
    • Optional. Advanced setup for non-default service naming.
  • --config PATH
    • Optional. Advanced setup for non-default config path.

Behavior

  • Removes service registration for the target install.
  • Performs best-effort unregister call to CertKit.
  • Removes installed agent files for the target install.

Examples

sudo certkit-agent uninstall
sudo certkit-agent uninstall --service-name edge-agent --config /opt/certkit/edge/config.json
certkit-agent.exe uninstall
certkit-agent.exe uninstall --service-name edge-agent --config "C:\ProgramData\CertKit\edge\config.json"

run

Synopsis

certkit-agent run [--key REGISTRATION_KEY] [--config PATH] [--once]

Options

  • --key REGISTRATION_KEY
    • Registration key used only if a new config must be created.
  • --config PATH
    • Optional. Advanced setup for non-default config path.
  • --once
    • Execute one poll and sync and exit.

Behavior

  • Loads or initializes config.
  • Registers on startup if registration is required.
  • Performs poll/sync work loop (or one-shot when --once is set).

Examples

certkit-agent run
certkit-agent run --once
certkit-agent run --key abc.xyz --config /etc/certkit-agent/config.json

register

Synopsis

certkit-agent register REGISTRATION_KEY [--config PATH]

Arguments

  • REGISTRATION_KEY (required, positional)

Options

  • --config PATH
    • Optional. Advanced setup for non-default config path.

Behavior

  • Writes/updates registration key in config.
  • Registers the agent and persists agent credentials.

Examples

certkit-agent register abc.xyz
certkit-agent register abc.xyz --config /etc/certkit-agent/config.json
certkit-agent.exe register abc.xyz
certkit-agent.exe register abc.xyz --config "C:\ProgramData\CertKit\certkit-agent\config.json"

validate

Synopsis

certkit-agent validate [--config PATH]

Options

  • --config PATH
    • Optional. Advanced setup for non-default config path.

Behavior

  • Validates config structure and required values.
  • Reports registration/keypair state and connectivity checks.
  • Returns non-zero exit code on validation failure.

Examples

certkit-agent validate
certkit-agent validate --config /etc/certkit-agent/config.json
certkit-agent.exe validate
certkit-agent.exe validate --config "C:\ProgramData\CertKit\certkit-agent\config.json"

version

Synopsis

certkit-agent version

Behavior

  • Prints the agent version string.

lock

Synopsis

certkit-agent lock [--config PATH]

Options

  • --config PATH
    • Optional. Advanced setup for non-default config path.

Behavior

  • Creates <config>.lock next to the config file (for example config.json.lock).
  • When locked, server updates are restricted to certificate updates. No new configuration changes or update command modifications are allowed from the CertKit app. This is a security feature to prevent unexpected changes from the app itself once everything is setup and working.

Examples

certkit-agent lock
certkit-agent lock --config /etc/certkit-agent/config.json
certkit-agent.exe lock
certkit-agent.exe lock --config "C:\ProgramData\CertKit\certkit-agent\config.json"

unlock

Synopsis

certkit-agent unlock [--config PATH]

Options

  • --config PATH
    • Optional. Advanced setup for non-default config path.

Behavior

  • Removes <config>.lock.
  • Unlock removes the lock file and allows the CertKit app to configure the agent again.
  • The agent can only be unlocked from the host itself. It cannot be unlocked from the CertKit application.

Examples

certkit-agent unlock
certkit-agent unlock --config /etc/certkit-agent/config.json
certkit-agent.exe unlock
certkit-agent.exe unlock --config "C:\ProgramData\CertKit\certkit-agent\config.json"

Operational Sequences

Install First, Register Later

sudo certkit-agent install --key abc.xyz --service-name edge-agent --config /opt/certkit/edge/config.json
sudo certkit-agent register abc.xyz --config /opt/certkit/edge/config.json
certkit-agent.exe install --key abc.xyz --service-name edge-agent --config "C:\ProgramData\CertKit\edge\config.json"
certkit-agent.exe register abc.xyz --config "C:\ProgramData\CertKit\edge\config.json"

Register First, Install Second

sudo certkit-agent register abc.xyz --config /opt/certkit/edge/config.json
sudo certkit-agent install --key abc.xyz --service-name edge-agent --config /opt/certkit/edge/config.json
certkit-agent.exe register abc.xyz --config "C:\ProgramData\CertKit\edge\config.json"
certkit-agent.exe install --key abc.xyz --service-name edge-agent --config "C:\ProgramData\CertKit\edge\config.json"

Cron (Linux, run --once)

# 1) Initialize config and register once
certkit-agent register abc.xyz --config /opt/certkit/cron/config.json
certkit-agent validate --config /opt/certkit/cron/config.json

# 2) Schedule recurring one-shot sync
(crontab -l 2>/dev/null; echo "*/5 * * * * /usr/local/bin/certkit-agent run --once --config /opt/certkit/cron/config.json >> /var/log/certkit-agent-cron.log 2>&1") | crontab -

Ad-Hoc Foreground (No Service Install)

# Register once (if not already registered)
certkit-agent register abc.xyz --config /tmp/certkit-agent/config.json

# Run daemon loop in the foreground
certkit-agent run --config /tmp/certkit-agent/config.json