From 746bc7548d358ba96bfa74e9ce6ceb06f11c550d Mon Sep 17 00:00:00 2001
From: Adrian <adrian@zyte.com>
Date: Fri, 31 Jul 2026 09:17:34 +0200
Subject: [PATCH] Clarify crawl vs runspider in help and docs (#7832)

---
 docs/topics/commands.rst     | 11 +++++++----
 scrapy/commands/crawl.py     |  2 +-
 scrapy/commands/runspider.py |  2 +-
 3 files changed, 9 insertions(+), 6 deletions(-)

diff --git a/docs/topics/commands.rst b/docs/topics/commands.rst
index e8a843e80..343193627 100644
--- a/docs/topics/commands.rst
+++ b/docs/topics/commands.rst
@@ -114,8 +114,8 @@ some usage help and the available commands::
       scrapy <command> [options] [args]
 
     Available commands:
-      crawl         Run a spider
       fetch         Fetch a URL using the Scrapy downloader
+      runspider     Run a spider from a Python file, no project required
     [...]
 
 The first line will print the currently active project if you're inside a
@@ -263,7 +263,9 @@ crawl
 * Syntax: ``scrapy crawl <spider>``
 * Requires project: *yes*
 
-Start crawling using a spider.
+Start crawling using the spider with the given :attr:`~scrapy.Spider.name`,
+which must be one of those that :command:`list` reports. To run a spider from a
+file instead, use :command:`runspider`.
 
 Supported options:
 
@@ -571,8 +573,9 @@ runspider
 * Syntax: ``scrapy runspider <spider_file.py>``
 * Requires project: *no*
 
-Run a spider self-contained in a Python file, without having to create a
-project.
+Run the spider defined in the given Python file, without requiring a project.
+
+Supported options: the same as :command:`crawl`.
 
 Example usage::
 
diff --git a/scrapy/commands/crawl.py b/scrapy/commands/crawl.py
index 866ba9f6b..4e086e057 100644
--- a/scrapy/commands/crawl.py
+++ b/scrapy/commands/crawl.py
@@ -16,7 +16,7 @@ class Command(BaseRunSpiderCommand):
         return "[options] <spider>"
 
     def short_desc(self) -> str:
-        return "Run a spider"
+        return "Run a spider of the current project, by name"
 
     def run(self, args: list[str], opts: argparse.Namespace) -> None:
         if len(args) < 1:
diff --git a/scrapy/commands/runspider.py b/scrapy/commands/runspider.py
index 0b9036457..9cdb393ab 100644
--- a/scrapy/commands/runspider.py
+++ b/scrapy/commands/runspider.py
@@ -38,7 +38,7 @@ class Command(BaseRunSpiderCommand):
         return "[options] <spider_file>"
 
     def short_desc(self) -> str:
-        return "Run a self-contained spider (without creating a project)"
+        return "Run a spider from a Python file, no project required"
 
     def long_desc(self) -> str:
         return "Run the spider defined in the given file"