Additional explanation/documentation

Signed-off-by: Alex Ellis (OpenFaaS Ltd) <[email protected]>

Author: alexellis

cmd/agent_logs.go

@@ -15,13 +15,16 @@ func makeAgentLogs() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "agent-logs",
 		Short: "Fetch logs from the agent's systemd service",
-		Example: `  # Latest logs for a given host:
+		Long: `Fetch the service logs from a remote server to if you need
+to confirm the rollout of updates, agent version, and to troubleshoot
+VM launches.`,
+		Example: `  # Latest logs for a given OWNER and HOST:
   actuated agent-logs --owner OWNER HOST
 
   # Latest logs for a given time-range
   actuated agent-logs --owner OWNER --age 1h HOST
   `,
-		Aliases: []string{"service-logs"},
+		Aliases: []string{"service-logs", "al"},
 	}
 
 	cmd.RunE = runAgentLogsE

cmd/disable.go

@@ -10,10 +10,13 @@ import (
 	"github.com/spf13/cobra"
 )
 
-func makeDisable() *cobra.Command {
+func makeDisableAgent() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "disable",
 		Short: "Disable the actuated service remotely.",
+		Long: `Disable the systemd service named actuated on the remote server, this should
+only be used when decommissioning a host. It can only be re-enabled by logging in via
+SSH and running "systemctl enable actuated".`,
 		Example: `  # Disable the actuated systemd service from restarting
 
   actuated-cli disable --owner ORG HOST

cmd/jobs.go

@@ -19,7 +19,27 @@ func makeJobs() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "jobs",
 		Short: "List jobs in the build queue",
-		Example: `  # Check queued and in_progress jobs for an organisation
+		Long: `List the queued and in_progress jobs for a OWNER or leave the option off
+to see all your authorized organisations.
+
+Troubleshooting:
+
+Why may a job be "stuck" as queued?
+
+You may have overloaded your runners so that jobs have been taken off the queue
+after to save thrashing. See also "actuated-cli repair"
+
+Why may a job be showing as in_progress for days?
+
+GitHub's API is often inconsistent, if you open the job page, you may see it's
+finished or cancelled, but still showing as running. This is a flaw in GitHub
+and they tend to clean these up periodically. We can mark it as hidden on our
+end if you reach out to support.
+`,
+		Example: `  # Check queued and in_progress jobs for your authorized orgs
+  actuated-cli jobs [--urls] 
+
+  # See jobs for a specific organisation, if you have access to multiple:
   actuated-cli jobs ORG
   
   # Get the same result, but in JSON format
@@ -33,9 +53,7 @@ func makeJobs() *cobra.Command {
 	cmd.RunE = runJobsE
 
 	cmd.Flags().BoolP("verbose", "v", false, "Show additional columns in the output")
-
 	cmd.Flags().BoolP("json", "j", false, "Request output in JSON format")
-
 	cmd.Flags().BoolP("urls", "u", false, "In verbose mode, control whether to include URLs (URLs always shown in non-verbose mode)")
 
 	return cmd
@@ -106,7 +124,7 @@ func runJobsE(cmd *cobra.Command, args []string) error {
 		if err := json.Unmarshal([]byte(res), &statuses); err != nil {
 			return err
 		}
-		
+
 		// In non-verbose mode, always show URLs
 		// In verbose mode, respect the --urls flag
 		showURL := !verbose || includeURL

cmd/logs.go

@@ -18,27 +18,45 @@ func makeLogs() *cobra.Command {
 		Long: `Fetch logs from a specific VM or a all VMs over a 
 range of time.`,
 
-		Example: `# Logs from all VMs over the past 15 minutes
-actuated-cli logs --owner=OWNER --age=15m HOST
-
-# Get the logs from a specific VM using its hostname as the --id
-actuated-cli logs --owner=OWNER --id=ID HOST
+		Example: `  # Default to get logs from all VMs from past 15 mins
+  actuated-cli logs --owner OWNER HOST		
+		
+  # Logs from all VMs over the past 1 hour
+  actuated-cli logs --owner OWNER --age 1h HOST
+
+  # Get the logs from a specific VM using its hostname as the --id
+  actuated-cli logs --owner OWNER --id ID HOST
 `,
 	}
 
 	cmd.RunE = runLogsE
+	cmd.PreRunE = preRunLogsE
+	cmd.Aliases = []string{"vm-logs", "l"}
 
 	cmd.Flags().StringP("owner", "o", "", "List logs owned by this user")
 	cmd.Flags().String("id", "", "ID variable for a specific runner VM hostname")
-	cmd.Flags().DurationP("age", "a", time.Minute*15, "Age of logs to fetch")
+	cmd.Flags().DurationP("age", "a", time.Minute*15, "Age of logs to fetch specified as a Go duration")
 
 	return cmd
 }
 
-func runLogsE(cmd *cobra.Command, args []string) error {
+func preRunLogsE(cmd *cobra.Command, args []string) error {
 	if len(args) < 1 {
 		return fmt.Errorf("specify the host as an argument")
 	}
+
+	ageChanged := cmd.Flags().Changed("age")
+	idChanged := cmd.Flags().Changed("id")
+
+	if ageChanged && idChanged {
+		return fmt.Errorf("--age can't be used with --id")
+	}
+
+	return nil
+
+}
+
+func runLogsE(cmd *cobra.Command, args []string) error {
 	host := strings.TrimSpace(args[0])
 
 	pat, err := getPat(cmd)

cmd/metering.go

@@ -14,7 +14,9 @@ func makeMetering() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "metering",
 		Short: "Fetch metering from a VM",
-		Long:  `Fetch the metering snapshot from a specific VM.`,
+		Long: `Fetch the metering snapshot from a specific VM generated by
+vmmeter. Note: this data is already collected on your behalf and appears under
+the "Profiling" tab in the actuated dashboard.`,
 
 		Example: `# Get the metering snapshot from a specific VM using its hostname as the --id
 actuated-cli metering --owner=OWNER --id=ID HOST

cmd/root.go

@@ -15,13 +15,16 @@ func init() {
 	root = &cobra.Command{
 		Use:   "actuated-cli",
 		Short: "The official CLI for actuated",
-		Long: `The actuated-cli is for customers and operators to query 
-the status of jobs and servers.
+		Long: `This CLI can be used to review and manage jobs, and the actuated
+agent installed on your servers.
 
-Run "actuated-cli auth" to get a Personal Access Token from GitHub
+The --owner flag or OWNER argument is a GitHub organization, i.e. for the path:
+self-actuated/actuated-cli, the owner is "self-actuated" also known as an org.
 
-See the project README on GitHub for more:
+Run "actuated-cli auth" to authenticate with GitHub.
 
+Learn more:
+https://docs.actuated.com/tasks/cli/
 https://github.com/self-actuated/actuated-cli
 `,
 		SilenceErrors: true,
@@ -39,24 +42,22 @@ https://github.com/self-actuated/actuated-cli
 		return nil
 	}
 
+	root.AddCommand(makeAuth())
+	root.AddCommand(MakeVersion())
+	root.AddCommand(makeSSH())
+
 	root.AddCommand(makeRunners())
 	root.AddCommand(makeJobs())
 	root.AddCommand(makeRepair())
-	root.AddCommand(makeRestart())
+	root.AddCommand(makeIncreases())
 
+	root.AddCommand(makeRestart())
 	root.AddCommand(makeAgentLogs())
-	root.AddCommand(makeLogs())
+	root.AddCommand(makeDisableAgent())
 	root.AddCommand(makeUpgrade())
-	root.AddCommand(makeIncreases())
-
-	root.AddCommand(makeSSH())
-	root.AddCommand(makeDisable())
-
-	root.AddCommand(makeAuth())
-	root.AddCommand(MakeVersion())
+	root.AddCommand(makeLogs())
 
 	root.AddCommand(makeController())
-
 	root.AddCommand(makeMetering())
 }
 

cmd/ssh_connect.go

@@ -12,7 +12,7 @@ import (
 	"strconv"
 	"strings"
 
-	"github.com/google/go-github/v52/github"
+	"github.com/google/go-github/v76/github"
 	"github.com/spf13/cobra"
 	"golang.org/x/oauth2"
 )

cmd/ssh_ls.go

@@ -11,7 +11,7 @@ import (
 	"strconv"
 	"time"
 
-	"github.com/google/go-github/v52/github"
+	"github.com/google/go-github/v76/github"
 	"github.com/olekukonko/tablewriter"
 	"github.com/spf13/cobra"
 	"golang.org/x/oauth2"

go.mod

@@ -1,10 +1,10 @@
 module github.com/self-actuated/actuated-cli
 
-go 1.22.0
+go 1.24.0
 
 require (
 	github.com/docker/go-units v0.5.0
-	github.com/google/go-github/v52 v52.0.0
+	github.com/google/go-github/v76 v76.0.0
 	github.com/morikuni/aec v1.0.0
 	github.com/olekukonko/tablewriter v0.0.5
 	github.com/spf13/cobra v1.8.1

go.sum

@@ -10,8 +10,8 @@ github.com/docker/go-units v0.5.0/go.mod h1:fgPhTUdO+D/Jk86RDLlptpiXQzgHJF7gydDD
 github.com/google/go-cmp v0.5.2/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
 github.com/google/go-cmp v0.5.9 h1:O2Tfq5qg4qc4AmwVlvv0oLiVAGB7enBSJ2x2DqQFi38=
 github.com/google/go-cmp v0.5.9/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
-github.com/google/go-github/v52 v52.0.0 h1:uyGWOY+jMQ8GVGSX8dkSwCzlehU3WfdxQ7GweO/JP7M=
-github.com/google/go-github/v52 v52.0.0/go.mod h1:WJV6VEEUPuMo5pXqqa2ZCZEdbQqua4zAk2MZTIo+m+4=
+github.com/google/go-github/v76 v76.0.0 h1:MCa9VQn+VG5GG7Y7BAkBvSRUN3o+QpaEOuZwFPJmdFA=
+github.com/google/go-github/v76 v76.0.0/go.mod h1:38+d/8pYDO4fBLYfBhXF5EKO0wA3UkXBjfmQapFsNCQ=
 github.com/google/go-querystring v1.1.0 h1:AnCroh3fv4ZBgVIf1Iwtovgjaw/GiKJo8M8yD/fhyJ8=
 github.com/google/go-querystring v1.1.0/go.mod h1:Kcdr2DB4koayq7X8pmAG4sNG59So17icRSOU623lUBU=
 github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=