Skip to content

cli.md

Latest commit

 

History

History
402 lines (308 loc) · 11.6 KB

cli.md

File metadata and controls

402 lines (308 loc) · 11.6 KB
Raw

CLI reference

The docksight binary installs, updates and inspects both halves of DockSight. This page documents every command that exists today, including the ones that are placeholders.

Command tree

docksight
├── install          Install the platform on this server
├── update           Update the CLI and/or the platform
├── status           Show platform status          (placeholder)
├── version          Show CLI and platform versions
└── agent
    ├── install      Install the agent on this host
    ├── update       Update the agent on this host
    ├── uninstall    Remove the agent               (placeholder)
    ├── start        Start the agent service        (placeholder)
    ├── stop         Stop the agent service         (placeholder)
    ├── restart      Restart the agent service      (placeholder)
    ├── status       Show agent service status      (placeholder)
    ├── logs         Show agent service logs        (placeholder)
    └── config       Show or update agent config

Placeholders exist so the command surface is discoverable, but they fail loudly rather than pretending to work:

$ sudo docksight agent status
✗ docksight agent status is not implemented yet

Global behaviour

Exit codes — 0 on success, 1 on any failure.

Error output — failures print once, prefixed with ✗, without a usage dump:

$ docksight agent install --url http://platform:2002
✗ system validation failed: the Docker daemon is not running: Cannot connect to the Docker daemon

A usage mistake still shows the flag reference:

$ docksight agent install --nope
✗ unknown flag: --nope
Usage:
  docksight agent install [flags]
Flags:
      --url string       DockSight platform URL, e.g. https://platform.example.com
      --version string   install a specific release tag instead of the latest

Privileges — every install and update command writes to /opt, /etc or /usr/local/bin and must run as root.

docksight install

Installs the platform on this server.

sudo docksight install

Flags: none.

What it does

  1. Validates OS, architecture, Docker Engine, Docker daemon and Compose
  2. Prints the resolved configuration
  3. Creates /opt/docksight and /var/lib/docksight
  4. Installs the running binary to /usr/local/bin/docksight
  5. Resolves the latest GitHub release
  6. Downloads and extracts the platform bundle
  7. Copies it into /opt/docksight
  8. Generates .env with fresh credentials (only if absent)
  9. Runs docker compose up -d
  10. Waits until every service is running and healthy

Output

$ sudo ./docksight-cli-v0.0.1-linux-amd64 install
→ [1/5] Checking operating system
✓ Checking operating system
...
→ Installing the CLI into /usr/local/bin/docksight
✓ CLI installed from /root/docksight-cli-v0.0.1-linux-amd64
→ Checking the latest DockSight release
✓ Latest release v0.0.1
✓ Installer package docksight-platform-v0.0.1.tar.gz found
→ Downloading installer package
✓ Download completed
✓ Platform installed
✓ Generated /opt/docksight/.env
→ Starting DockSight services
→ Waiting for services to become ready
✓ postgres: running (healthy)
✓ redis: running (healthy)
✓ server: running
✓ web: running
✓ nginx: running
✓ DockSight is running on http://localhost:2002

Safe to re-run. A second run upgrades the bundle, preserves .env, and recreates the stack.

docksight update

Updates the CLI and the platform. They are versioned independently.

sudo docksight update
Flag Type Description
--cli bool Update only the CLI binary
--platform bool Update only the platform bundle
--version string Target a specific release tag instead of the latest
--force bool Re-apply even if already at the target version

--cli and --platform are mutually exclusive.

Examples

sudo docksight update                      # both, to latest
sudo docksight update --platform           # platform only
sudo docksight update --cli                # CLI only, stack untouched
sudo docksight update --version v0.0.2     # pin to a specific release
sudo docksight update --version v0.0.1     # roll back to an earlier one
sudo docksight update --force              # re-apply current version

Output when already current

$ sudo docksight update
→ Checking the latest DockSight release
✓ Latest release v0.0.1
→ CLI already at v0.0.1
→ Platform already at v0.0.1
✓ DockSight is up to date

Internal behaviour — reads /opt/docksight/state.json to decide what needs work. A platform update replaces the bundle then runs compose down and up, so there is a brief outage. .env and named volumes survive.

docksight version

$ docksight version
→ CLI version: v0.0.1
→ Commit: a1b2c3d
→ Build date: 2026-08-07T14:00:00Z
→ Platform version: v0.0.1

On a host with no platform installed:

$ docksight version
→ CLI version: v0.0.1
→ Commit: a1b2c3d
→ Build date: 2026-08-07T14:00:00Z
→ Platform version: not installed

The CLI version, commit, and UTC build date are stamped at build time with -ldflags. A plain local build reports dev for the version and commit, and unknown for the build date. The platform version comes from state.json.

docksight status

$ docksight status
→ DockSight status: all active

!!! warning "Placeholder" This prints a fixed string and does not inspect anything. Use docker compose -f /opt/docksight/dockersight-installation.yml ps instead. Tracked in the Roadmap.

docksight agent install

Installs the agent on this Docker host.

sudo docksight agent install --url https://platform.example.com
Flag Type Description
--url string Platform URL. Prompts interactively if omitted.
--version string Install a specific release tag instead of the latest

Examples

# Interactive
sudo docksight agent install

# Non-interactive (required in scripts — a prompt would hang)
sudo docksight agent install --url https://platform.example.com

# Pinned
sudo docksight agent install --url https://platform.example.com --version v0.0.1

# Plain HTTP on a private network
sudo docksight agent install --url http://10.0.0.5:2002

Output

→ Agent binary:  /usr/local/bin/docksight-agent
→ Configuration: /etc/docksight-agent/config.yaml
→ Service:       docksight-agent.service
→ Platform:      wss://platform.example.com/agents
→ Validating the host
→ [1/6] Checking operating system
✓ Checking operating system
→ [2/6] Checking architecture
✓ Checking architecture
→ [3/6] Checking Docker Engine
✓ Checking Docker Engine
→ [4/6] Checking Docker daemon
✓ Checking Docker daemon
→ [5/6] Checking systemd
✓ Checking systemd
→ [6/6] Checking internet connectivity
✓ Checking internet connectivity
→ Checking the latest DockSight release
✓ Latest release v0.0.1
→ Downloading docksight-agent-v0.0.1-linux-amd64
✓ Agent binary installed at /usr/local/bin/docksight-agent
→ Writing /etc/docksight-agent/config.yaml
✓ Configured platform wss://platform.example.com/agents
→ Identity will be created at /etc/docksight-agent/identity.json on first connection
→ Creating the systemd service
✓ Unit written to /etc/systemd/system/docksight-agent.service
✓ Service enabled at boot
→ Starting docksight-agent.service
✓ docksight-agent.service is running
✓ Agent connected to wss://platform.example.com/agents
✓ DockSight Agent installed and connected

Safe to re-run. Re-running upgrades the binary, rewrites the config and restarts the service. identity.json is preserved, so the host keeps its registration.

!!! note "This command does not put the CLI on PATH" Only docksight install self-installs. On an agent-only host, keep the downloaded binary or move it yourself: sudo mv docksight-cli-* /usr/local/bin/docksight.

docksight agent update

Updates the agent, reusing the platform URL already on disk.

sudo docksight agent update
Flag Type Description
--version string Update to a specific release tag instead of the latest
--url string Repoint the agent at a different platform

Examples

sudo docksight agent update                                    # latest
sudo docksight agent update --version v0.0.2                   # pinned
sudo docksight agent update --version v0.0.1                   # roll back
sudo docksight agent update --url https://new-platform.example.com

With no agent installed

$ sudo docksight agent update
✗ no agent installation found at /etc/docksight-agent/config.yaml: run 'docksight agent install --url ...' first

Internal behaviour — identical to agent install, except the platform URL is read from config.yaml instead of a flag. Retyping a URL is how a wrong port gets introduced, so the update path avoids it.

docksight agent config

With no flags, displays the effective agent configuration without printing the contents of identity.json:

$ sudo docksight agent config
→ Agent configuration:
→ Platform URL:  wss://platform.example.com/agents
→ Binary path:   /usr/local/bin/docksight-agent
→ Config path:   /etc/docksight-agent/config.yaml
→ Unit name:     docksight-agent.service
→ Docker socket: /var/run/docker.sock
→ Registered:    yes

Change only the platform URL with --set-url:

$ sudo docksight agent config --set-url https://other.example.com
✓ Platform URL updated to wss://other.example.com/agents
✓ docksight-agent.service restarted

The URL is validated and normalized before config.yaml is written. Invalid input leaves the file unchanged. Other configuration values are preserved, and identity.json is never opened or modified.

Placeholder commands

These are declared but not implemented:

Command Use instead
docksight agent uninstall Manual steps in Installation
docksight agent start sudo systemctl start docksight-agent
docksight agent stop sudo systemctl stop docksight-agent
docksight agent restart sudo systemctl restart docksight-agent
docksight agent status systemctl status docksight-agent
docksight agent logs journalctl -u docksight-agent -f

Common workflows

=== "First platform install"

```bash
curl -fLO https://github.com/Open-Source-Kigali/docksight/releases/latest/download/docksight-cli-v0.0.1-linux-amd64
chmod +x docksight-cli-v0.0.1-linux-amd64
sudo ./docksight-cli-v0.0.1-linux-amd64 install
```

=== "Add a Docker host"

```bash
curl -fLO https://github.com/Open-Source-Kigali/docksight/releases/latest/download/docksight-cli-v0.0.1-linux-amd64
chmod +x docksight-cli-v0.0.1-linux-amd64
sudo ./docksight-cli-v0.0.1-linux-amd64 agent install --url https://platform.example.com
```

=== "Upgrade everything"

```bash
# On the platform server
sudo docksight update

# On each agent host
sudo docksight agent update
```

=== "Roll back one agent"

```bash
sudo docksight agent update --version v0.0.1
```

Related

  • Installation — walkthroughs and troubleshooting
  • Platform — what install and update actually change
  • Agent — configuration and service management