Document CLI discovery and storage commands

Author: artpar

README.md

@@ -2,7 +2,27 @@
 
 CLI client for [Daptin](https://github.com/daptin/daptin) — the headless CMS and API server.
 
-All Daptin entities are accessed uniformly via CRUD commands. All Daptin actions (signin, signup, upload, export, etc.) are executed uniformly via `execute`. No special-case commands.
+All Daptin entities are accessed uniformly via CRUD commands, and all Daptin actions can be executed uniformly via `execute`. Common workflows such as cloud storage and file asset uploads also have ergonomic wrapper commands.
+
+## Discovery
+
+The CLI is self-describing. Start with:
+
+```bash
+daptin-cli --help
+daptin-cli list --help
+daptin-cli execute --help
+daptin-cli describe action --help
+daptin-cli storage --help
+daptin-cli asset --help
+```
+
+For any Daptin action, use `describe action` before `execute` to see whether the action needs an instance reference id and which input fields it accepts:
+
+```bash
+daptin-cli describe action integration install_integration
+daptin-cli execute integration install_integration --reference-id <integration_reference_id>
+```
 
 ## Install
 
@@ -50,14 +70,17 @@ Grab a binary from the [releases page](https://github.com/daptin/daptin-cli/rele
 daptin-cli context add myserver http://localhost:6336
 daptin-cli context set myserver
 
-# Sign in (signin is just an action like any other)
+# Sign in (signin is an action like any other)
 daptin-cli execute user_account signin email=admin@example.com password=secret
 
 # List tables
 daptin-cli list --columns table_name,is_top_level world
 
 # List rows
 daptin-cli list --columns name,email --page-size 20 user_account
+
+# Discover action requirements
+daptin-cli describe action integration install_integration
 ```
 
 ## Context Management
@@ -95,6 +118,7 @@ daptin-cli list --columns table_name,reference_id --page-size 50 world
 daptin-cli list --sort -created_at --page-size 10 document
 
 # Filter
+daptin-cli list --filter name=administrators usergroup
 daptin-cli list --filter "status is active" task
 daptin-cli list --filter "table_name like %doc%" world
 daptin-cli list --filter "name is admin;email contains example" user_account
@@ -139,7 +163,7 @@ daptin-cli related document <ref_id> user_account_id
 
 ## Actions
 
-All Daptin actions — built-in or custom — are executed with `execute`. There are no special commands for signin, signup, upload, etc.
+All Daptin actions — built-in or custom — can be executed with `execute`.
 
 ```bash
 daptin-cli execute <entity> <action_name> [key=val ...]
@@ -196,6 +220,12 @@ For actions that require an entity instance, pass `--reference-id`:
 daptin-cli execute cloud_store upload_file --reference-id <cloud_store_id> path=/docs
 ```
 
+Use `describe action` when you are unsure:
+
+```bash
+daptin-cli describe action cloud_store upload_file
+```
+
 ## Describe
 
 ### Table schema
@@ -212,7 +242,54 @@ Shows columns (name + type) and available actions.
 daptin-cli describe action document createDocument
 ```
 
-Shows the action's InFields (the parameters it accepts).
+Shows whether the action is instance-bound, whether `--reference-id` is required, the action's InFields, and an example `execute` command.
+
+## Storage
+
+Cloud storage setup and common file operations are available through `storage`.
+
+```bash
+# Create a local store
+daptin-cli storage add local-files \
+  --type local \
+  --store-provider local \
+  --root-path /tmp/daptin-files
+
+# Create an S3/MinIO-style store and linked credential
+daptin-cli storage add minio \
+  --type s3 \
+  --provider Minio \
+  --endpoint http://localhost:9000 \
+  --access-key minioadmin \
+  --secret-key minioadmin123 \
+  --bucket daptin-test \
+  --restart
+
+# List and remove stores
+daptin-cli storage list
+daptin-cli storage remove minio
+```
+
+File operations use `store-name:/path` addressing:
+
+```bash
+daptin-cli storage mkdir local-files:/photos
+daptin-cli storage upload local-files:/photos ./image.jpg
+daptin-cli storage upload local-files:/site ./public --recursive
+daptin-cli storage mv local-files:/photos/image.jpg local-files:/archive/image.jpg
+daptin-cli storage rm local-files:/archive/image.jpg
+```
+
+Direct `storage ls` and `storage download` for `cloud_store` paths are intentionally not implemented as direct cloud-store commands because Daptin exposes those flows through site file actions and asset routes, not direct `cloud_store` actions.
+
+## Asset Columns
+
+Use `asset` for `file.*` columns on normal entity rows. These commands use Daptin's `/asset/...` routes.
+
+```bash
+daptin-cli asset upload product <product_reference_id> photo ./image.jpg
+daptin-cli asset list product <product_reference_id> photo
+```
 
 ## Output
 
@@ -225,9 +302,10 @@ daptin-cli --output json list world
 
 ## Filter Syntax
 
-Filters are semicolon-separated `<column> <operator> <value>` expressions:
+Filters can use `key=value` shorthand or semicolon-separated `<column> <operator> <value>` expressions:
 
 ```bash
+--filter "name=alice"
 --filter "name is alice"
 --filter "status is active;role is admin"
 --filter "name like %ali%"

cmd/action.go

@@ -18,8 +18,13 @@ import (
 func executeCommand(appCtx *AppContext) *cli.Command {
 	return &cli.Command{
 		Name:      "execute",
-		Usage:     "Execute an action on an entity",
+		Usage:     "Execute a Daptin action on an entity",
 		ArgsUsage: "<entity> <action_name> [key=val ...]",
+		UsageText: `daptin execute <entity> <action_name> [key=val ...]
+   daptin execute user_account signin email=admin@example.com password=secret
+   daptin execute integration install_integration --reference-id <integration_reference_id>
+   daptin execute user_account signin --interactive`,
+		Description: "Use describe action first when you need to know whether an action requires --reference-id or which fields it accepts.",
 		Flags: []cli.Flag{
 			&cli.StringFlag{
 				Name:  "reference-id",

cmd/crud.go

@@ -17,6 +17,10 @@ func listCommand(appCtx *AppContext) *cli.Command {
 		Name:      "list",
 		Usage:     "List rows of an entity",
 		ArgsUsage: "<entity>",
+		UsageText: `daptin list <entity> [flags]
+   daptin list usergroup --filter name=administrators --columns name,reference_id
+   daptin list world --filter "table_name like %doc%" --page-size 50
+   daptin list document --sort -created_at`,
 		Flags: []cli.Flag{
 			&cli.StringFlag{
 				Name:  "columns",
@@ -38,7 +42,7 @@ func listCommand(appCtx *AppContext) *cli.Command {
 			},
 			&cli.StringFlag{
 				Name:  "filter",
-				Usage: "Filter expression",
+				Usage: "Filter expression, e.g. name=value or \"name is value\"",
 			},
 			&cli.StringFlag{
 				Name:  "include",

cmd/describe.go

@@ -38,8 +38,11 @@ func describeCommand(appCtx *AppContext) *cli.Command {
 			},
 			{
 				Name:      "action",
-				Usage:     "Show action schema (InFields, OutFields)",
+				Usage:     "Show action schema, fields, and reference-id requirement",
 				ArgsUsage: "<entity> <action_name>",
+				UsageText: `daptin describe action <entity> <action_name>
+   daptin describe action integration install_integration
+   daptin describe action user_account signin`,
 				Action: func(c *cli.Context) error {
 					entityName := c.Args().Get(0)
 					actionName := c.Args().Get(1)

cmd/storage.go

@@ -20,6 +20,14 @@ func storageCommand(appCtx *AppContext) *cli.Command {
 	return &cli.Command{
 		Name:  "storage",
 		Usage: "Manage Daptin cloud stores and storage actions",
+		UsageText: `daptin storage <command> [options]
+   daptin storage list
+   daptin storage add minio --type s3 --provider Minio --endpoint http://localhost:9000 --access-key minioadmin --secret-key minioadmin123 --bucket daptin-test
+   daptin storage add local-files --type local --store-provider local --root-path /tmp/daptin-files
+   daptin storage upload local-files:/photos ./image.jpg
+   daptin storage mkdir local-files:/photos
+   daptin storage rm local-files:/photos/old.jpg`,
+		Description: "These commands wrap Daptin's cloud_store records and supported cloud_store actions. Direct cloud_store ls/download are not exposed by Daptin; use site file actions or asset routes for those flows.",
 		Subcommands: []*cli.Command{
 			storageAddCommand(appCtx),
 			storageListCommand(appCtx),
@@ -39,6 +47,10 @@ func storageAddCommand(appCtx *AppContext) *cli.Command {
 		Name:      "add",
 		Usage:     "Create a cloud_store and optional rclone credential",
 		ArgsUsage: "<name>",
+		UsageText: `daptin storage add <name> [flags]
+   daptin storage add minio --type s3 --provider Minio --endpoint http://localhost:9000 --access-key minioadmin --secret-key minioadmin123 --bucket daptin-test
+   daptin storage add local-files --type local --store-provider local --root-path /tmp/daptin-files
+   daptin storage add s3-prod --type s3 --provider AWS --bucket prod-bucket --param region=us-east-1 --restart`,
 		Flags: []cli.Flag{
 			&cli.StringFlag{Name: "type", Value: "s3", Usage: "Rclone storage type"},
 			&cli.StringFlag{Name: "provider", Usage: "Rclone credential provider name"},
@@ -132,8 +144,9 @@ func storageAddCommand(appCtx *AppContext) *cli.Command {
 
 func storageListCommand(appCtx *AppContext) *cli.Command {
 	return &cli.Command{
-		Name:  "list",
-		Usage: "List configured cloud stores",
+		Name:      "list",
+		Usage:     "List configured cloud stores",
+		UsageText: `daptin storage list`,
 		Action: func(c *cli.Context) error {
 			result, err := appCtx.Client.FindAll("cloud_store", daptinClient.DaptinQueryParameters{"page[size]": 500})
 			if err != nil {
@@ -150,6 +163,8 @@ func storageRemoveCommand(appCtx *AppContext) *cli.Command {
 		Name:      "remove",
 		Usage:     "Delete a cloud_store by name or reference_id",
 		ArgsUsage: "<name-or-reference-id>",
+		UsageText: `daptin storage remove <name-or-reference-id>
+   daptin storage remove local-files`,
 		Action: func(c *cli.Context) error {
 			ref, err := cloudStoreRef(appCtx, c.Args().Get(0))
 			if err != nil {
@@ -169,6 +184,10 @@ func storageUploadCommand(appCtx *AppContext) *cli.Command {
 		Name:      "upload",
 		Usage:     "Upload a file or recursive directory to cloud_store via upload_file",
 		ArgsUsage: "<store:/path> <local-path>",
+		UsageText: `daptin storage upload <store:/path> <local-path>
+   daptin storage upload local-files:/photos ./image.jpg
+   daptin storage upload local-files:/docs/ ./manual.pdf
+   daptin storage upload local-files:/site/ ./public --recursive`,
 		Flags: []cli.Flag{
 			&cli.BoolFlag{Name: "recursive", Usage: "Upload a directory recursively"},
 		},
@@ -198,6 +217,8 @@ func storageMkdirCommand(appCtx *AppContext) *cli.Command {
 		Name:      "mkdir",
 		Usage:     "Create a folder in cloud_store",
 		ArgsUsage: "<store:/path>",
+		UsageText: `daptin storage mkdir <store:/path>
+   daptin storage mkdir local-files:/photos`,
 		Action: func(c *cli.Context) error {
 			storeName, targetPath, err := parseStorageAddress(c.Args().Get(0))
 			if err != nil {
@@ -217,6 +238,8 @@ func storageRemovePathCommand(appCtx *AppContext) *cli.Command {
 		Name:      "rm",
 		Usage:     "Delete a path from cloud_store",
 		ArgsUsage: "<store:/path>",
+		UsageText: `daptin storage rm <store:/path>
+   daptin storage rm local-files:/photos/old.jpg`,
 		Action: func(c *cli.Context) error {
 			storeName, targetPath, err := parseStorageAddress(c.Args().Get(0))
 			if err != nil {
@@ -232,6 +255,8 @@ func storageMoveCommand(appCtx *AppContext) *cli.Command {
 		Name:      "mv",
 		Usage:     "Move or rename a path in the same cloud_store",
 		ArgsUsage: "<store:/source> <store:/destination>",
+		UsageText: `daptin storage mv <store:/source> <store:/destination>
+   daptin storage mv local-files:/old.jpg local-files:/archive/old.jpg`,
 		Action: func(c *cli.Context) error {
 			srcStore, source, err := parseStorageAddress(c.Args().Get(0))
 			if err != nil {
@@ -263,6 +288,10 @@ func assetCommand(appCtx *AppContext) *cli.Command {
 	return &cli.Command{
 		Name:  "asset",
 		Usage: "Manage file asset columns",
+		UsageText: `daptin asset <command> [options]
+   daptin asset upload product <product_reference_id> photo ./image.jpg
+   daptin asset list product <product_reference_id> photo`,
+		Description: "Asset commands use Daptin's /asset routes for file.* columns on normal entity rows.",
 		Subcommands: []*cli.Command{
 			assetUploadCommand(appCtx),
 			assetListCommand(appCtx),
@@ -275,6 +304,8 @@ func assetUploadCommand(appCtx *AppContext) *cli.Command {
 		Name:      "upload",
 		Usage:     "Stream a file into a file.* asset column",
 		ArgsUsage: "<entity> <reference_id> <column> <local-file>",
+		UsageText: `daptin asset upload <entity> <reference_id> <column> <local-file>
+   daptin asset upload product <product_reference_id> photo ./image.jpg`,
 		Action: func(c *cli.Context) error {
 			entityName, referenceID, columnName, localPath := c.Args().Get(0), c.Args().Get(1), c.Args().Get(2), c.Args().Get(3)
 			if entityName == "" || referenceID == "" || columnName == "" || localPath == "" {
@@ -314,6 +345,8 @@ func assetListCommand(appCtx *AppContext) *cli.Command {
 		Name:      "list",
 		Usage:     "List files recorded in a file.* asset column",
 		ArgsUsage: "<entity> <reference_id> <column>",
+		UsageText: `daptin asset list <entity> <reference_id> <column>
+   daptin asset list product <product_reference_id> photo`,
 		Action: func(c *cli.Context) error {
 			entityName, referenceID, columnName := c.Args().Get(0), c.Args().Get(1), c.Args().Get(2)
 			if entityName == "" || referenceID == "" || columnName == "" {