Command descriptions. Closes #111

cmd/collect.go

@@ -28,12 +28,14 @@ import (
 
 func collectCmd() *cobra.Command {
 	cmd := &cobra.Command{
-		Use:              "collect [flags]",
+		Use:              "collect [table|table.partition] [flags]",
 		Args:             cobra.ArbitraryArgs,
 		TraverseChildren: true,
 		Run:              runCollectCmd,
-		Short:            "Collect logs from configured sources",
-		Long:             `Collect logs from configured sources.`,
+		Short:            "Run a collection",
+		Long: `The tailpipe collect command runs a plugin that reads from a source and writes to the hive. 
+		
+Every time you run tailpipe collect, Tailpipe refreshes its views over all collected parquet files.`,
 	}
 	// arg `from` accepts:
 	// - ISO 8601 date (2024-01-01)
@@ -44,7 +46,7 @@ func collectCmd() *cobra.Command {
 
 	cmdconfig.OnCmd(cmd).
 		AddBoolFlag(pconstants.ArgCompact, true, "Compact the parquet files after collection").
-		AddStringFlag(pconstants.ArgFrom, "", "Specify the collection start time").
+		AddStringFlag(pconstants.ArgFrom, "", "Collect days newer than a relative or absolute date (collection defaulting to 7 days if not specified)").
 		AddBoolFlag(pconstants.ArgTiming, false, "Show timing information")
 
 	return cmd

cmd/compact.go

@@ -18,11 +18,11 @@ import (
 
 func compactCmd() *cobra.Command {
 	cmd := &cobra.Command{
-		Use:   "compact [flags]",
+		Use:   "compact [table|table.partition] [flags]",
 		Args:  cobra.ArbitraryArgs,
 		Run:   runCompactCmd,
-		Short: "compact the data files",
-		Long:  `compact the parquet data files into one file per day.`,
+		Short: "Compact multiple parquet files per day to one per day",
+		Long:  `Compact multiple parquet files per day to one per day.`,
 	}
 
 	cmdconfig.OnCmd(cmd)

cmd/connect.go

@@ -37,8 +37,8 @@ func connectCmd() *cobra.Command {
 		Use:   "connect [flags]",
 		Args:  cobra.ArbitraryArgs,
 		Run:   runConnectCmd,
-		Short: "return a connection string for a database with a schema determined by the provided parameters",
-		Long:  `return a connection string for a database with a schema determined by the provided parameters.`,
+		Short: "Return a connection string for a database, with a schema determined by the provided parameters",
+		Long:  `Return a connection string for a database, with a schema determined by the provided parameters.`,
 	}
 
 	// args `from` and `to` accept:

cmd/partition.go

@@ -30,7 +30,7 @@ func partitionCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "partition [command]",
 		Args:  cobra.NoArgs,
-		Short: "Tailpipe partition commands.",
+		Short: "List, show, and delete Tailpipe partitions",
 		Long: `Tailpipe partition commands.
 
 Partitions are instances of Tailpipe tables with a defined source and configuration.
@@ -108,7 +108,7 @@ func partitionShowCmd() *cobra.Command {
 		Use:   "show",
 		Args:  cobra.ExactArgs(1),
 		Run:   runPartitionShowCmd,
-		Short: "Show details for a specific partition.",
+		Short: "Show details for a specific partition",
 		Long:  `Show details for a specific partition.`,
 	}
 
@@ -158,8 +158,8 @@ func partitionDeleteCmd() *cobra.Command {
 		Use:   "delete ",
 		Args:  cobra.ExactArgs(1),
 		Run:   runPartitionDeleteCmd,
-		Short: "delete a partition for the specified period",
-		Long:  `delete a partition for the specified period`,
+		Short: "Delete a partition for the specified period",
+		Long:  `Delete a partition for the specified period`,
 	}
 
 	// args `from` and `to` accept:

cmd/query.go

@@ -22,12 +22,19 @@ var queryOutputMode = constants.QueryOutputModeTable
 
 func queryCmd() *cobra.Command {
 	cmd := &cobra.Command{
-		Use:              "query [sql]",
+		Use:              "query [sql] [flags]",
 		Args:             cobra.MaximumNArgs(1),
 		TraverseChildren: true,
 		Run:              runQueryCmd,
-		Short:            "execute a query against the workspace database",
-		Long:             `execute a query against the workspace database.`,
+		Short:            "Execute a query against the workspace database",
+		Long: `Execute SQL queries interactively, or by a query argument.
+
+To open the interactive query shell, run tailpipe query with no arguments. The query shell 
+provides a way to explore your data and run multiple queries.
+
+If a query string is passed on the command line then it will be run immediately and the command 
+will exit. Alternatively, you may specify one or more files containing SQL statements. You can 
+run multiple SQL files by passing a glob or a space-separated list of file names.`,
 	}
 
 	// args `from` and `to` accept:

cmd/source.go

@@ -23,7 +23,7 @@ func sourceCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "source [command]",
 		Args:  cobra.NoArgs,
-		Short: "Tailpipe source commands.",
+		Short: "List and show Tailpipe sources",
 		Long: `Tailpipe source commands.
 
 Sources extend Tailpipe to obtain data from many different services and providers.
@@ -100,7 +100,7 @@ func sourceShowCmd() *cobra.Command {
 		Use:   "show [source]",
 		Args:  cobra.ExactArgs(1),
 		Run:   runSourceShowCmd,
-		Short: "Show details for a specific source.",
+		Short: "Show details for a specific source",
 		Long:  `Show details for a specific source.`,
 	}
 

cmd/table.go

@@ -23,7 +23,7 @@ func tableCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "table [command]",
 		Args:  cobra.NoArgs,
-		Short: "Tailpipe table commands.",
+		Short: "List and show Tailpipe tables",
 		Long: `Tailpipe table commands.
 
 Tables define the structure of the data that is collected by Tailpipe.

internal/constants/descriptions.go

@@ -1,6 +1,32 @@
 package constants
 
 const (
-	TailpipeShortDescription = ""
-	TailpipeLongDescription  = ``
+	TailpipeShortDescription = "Collect, store and analyze log data using SQL"
+	TailpipeLongDescription  = `
+Tailpipe: select * from logs;
+	
+Tailpipe is a high-performance data collection and querying tool that makes it 
+easy to collect, store, and analyze log data. With Tailpipe you can:
+
+  - Collect logs from various sources and store them efficiently
+  - Query your data with familiar SQL syntax using Tailpipe (or DuckDB!)
+  - Use Powerpipe to visualize your logs and run detections
+
+Common commands:
+
+  # Install a plugin from the hub - https://hub.tailpipe.io
+  tailpipe plugin install aws
+
+  # Run a collection
+  tailpipe collect aws_cloudtrail_log.cloudtrail_logs
+
+  # Execute a defined SQL query
+  tailpipe query "select * from aws_cloudtrail_log"
+
+  # Get help for a command
+  tailpipe help query
+
+Documentation:
+  https://tailpipe.io/docs
+`
 )