Update docs and examples for new standalone CLI (#524)

* Update docs for standalond CLI usage

* Update examples for standalond CLI usage

* Refine some expressions to make docs clearer

Author: lemorage

docs/docs/core/cli.mdx

@@ -8,60 +8,39 @@ import TabItem from '@theme/TabItem';
 
 # CocoIndex CLI
 
-CocoIndex CLI embeds CLI functionality in your program.
-It provides a bunch of commands for easily managing and inspecting your flows and indexes.
+CocoIndex CLI is a standalone tool for easily managing and inspecting your flows and indexes.
 
-## Enable CocoIndex CLI
+## Invoking the CLI
 
-### Use Packaged Main
+Once CocoIndex is installed, you can invoke the CLI directly using the `cocoindex` command. Most commands require an `APP_TARGET` argument, which tells the CLI where your flow definitions are located.
 
-The easiest way is to use a packaged main function:
+**APP_TARGET Format:**
 
-<Tabs>
-<TabItem value="python" label="Python" default>
+The `APP_TARGET` can be:
+1.  A **path to a Python file** defining your flows (e.g., `main.py`, `path/to/my_flows.py`).
+2.  An **installed Python module name** that contains your flow definitions (e.g., `my_package.flows`).
+3.  For commands that operate on a *specific flow* (like `show`, `update`, `evaluate`), you can combine the application reference with a flow name:
+    * `path/to/my_flows.py:MyFlow`
+    * `my_package.flows:MyFlow`
 
-```python title="main.py"
-import cocoindex
+**Global Options:**
 
-@cocoindex.main_fn()
-def main():
-  ...
-```
+* `--env-file <path>`: Load environment variables from a specified `.env` file. If not provided, `.env` in the current directory is loaded if it exists.
+* `--version`: Show the CocoIndex version and exit.
+* `--help`: Show the main help message and exit.
 
-</TabItem>
-</Tabs>
-
-With this, when the program is executed with `cocoindex` as its first argument, CocoIndex CLI will take over the control. For example:
-
-```sh
-$ python main.py cocoindex ls       # Run "ls" subcommand: list all flows
-```
-
-You may also provide a `cocoindex_cmd` argument to the `main_fn` decorator to change the command from `cocoindex` to something else.
-
-### Explicitly CLI Invoke
-
-An alternative way is to use `cocoindex.cli.cli` (with type [`click.Group`](https://click.palletsprojects.com/en/stable/api/#click.Group)).
-For example, you may invoke the CLI explicitly with additional arguments:
-
-<Tabs>
-<TabItem value="python" label="Python" default>
-
-```python
-cocoindex.cli.cli.main(args)
-```
-
-</TabItem>
-</Tabs>
+:::caution Deprecated Usage
+The old method of invoking the CLI using `python main.py cocoindex ...` via the `@cocoindex.main_fn()` decorator is now deprecated. Please remove `@cocoindex.main_fn()` from your scripts and use the standalone cocoindex command as described.
+:::
 
 ## Subcommands
 
 The following subcommands are available:
 
 | Subcommand | Description |
 | ---------- | ----------- |
-| `ls` | List all flows present in the current process. Or list all persisted flows under the current app namespace if `--all` is specified. |
-| `show` | Show the spec for a specific flow. |
+| `ls` | List all flows present in the given file/module. Or list all persisted flows under the current app namespace if no file/module specified. |
+| `show` | Show the spec and schema for a specific flow. |
 | `setup` | Check and apply backend setup changes for flows, including the internal and target storage (to export). |
 | `drop` | Drop the backend setup for specified flows. |
 | `update` | Update the index defined by the flow. |
@@ -71,6 +50,6 @@ The following subcommands are available:
 Use `--help` to see the full list of subcommands, and `subcommand --help` to see the usage of a specific one.
 
 ```sh
-python main.py cocoindex --help       # Show all subcommands
-python main.py cocoindex show --help  # Show usage of "show" subcommand
+cocoindex --help       # Show all subcommands
+cocoindex show --help  # Show usage of "show" subcommand
 ```

docs/docs/core/flow_methods.mdx

@@ -30,17 +30,7 @@ def demo_flow(flow_builder: cocoindex.FlowBuilder, data_scope: cocoindex.DataSco
 ```
 
 It creates a `demo_flow` object in `cocoindex.Flow` type.
-To enable CLI, you also need to make sure you have a main function decorated with `@cocoindex.main_fn()`:
 
-
-```python title="main.py"
-@cocoindex.main_fn()
-def main():
-    ...
-
-if __name__ == "__main__":
-    main()
-```
 </TabItem>
 </Tabs>
 
@@ -78,7 +68,7 @@ The `cocoindex update` subcommand creates/updates data in the target storage.
 Once it's done, the target data is fresh up to the moment when the function is called.
 
 ```sh
-python main.py cocoindex update
+cocoindex update main.py
 ```
 
 #### Library API
@@ -115,7 +105,7 @@ Change capture mechanisms enable CocoIndex to continuously capture changes from
 To perform live update, run the `cocoindex update` subcommand with `-L` option:
 
 ```sh
-python main.py cocoindex update -L
+cocoindex update main.py -L
 ```
 
 If there's at least one data source with change capture mechanism enabled, it will keep running until the aborted (e.g. by `Ctrl-C`).
@@ -232,7 +222,7 @@ It takes the following options:
 Example:
 
 ```sh
-python main.py cocoindex evaluate --output-dir ./eval_output
+cocoindex evaluate main.py --output-dir ./eval_output
 ```
 
 ### Library API

docs/docs/core/initialization.mdx

@@ -15,42 +15,42 @@ We'll talk about the code skeleton to initialize the library in your code, and t
 
 There're two options to initialize in your code:
 
-*   Use packaged main function. It's easier to start with.
+*   Use Cocoindex CLI. It's easier to start with.
 *   Explicit initialization. It's more flexible.
 
-### Packaged Main
+### CLI-Based Initialization
 
-The easiest way is to use a packaged main function:
+When you use the `cocoindex` command-line tool, the library is automatically initialized for you:
 
-<Tabs>
-<TabItem value="python" label="Python" default>
+1. **Environment File Loading**:
+    *   By default, the `cocoindex` CLI searches upward from the current directory for a `.env` file.
+    *   You can use `--env-file <path>` to specify one explicitly:
 
-The `@cocoindex.main_fn` decorator wraps your main function for CocoIndex:
-
-```python
-import cocoindex
+        ```sh
+        cocoindex --env-file path/to/custom.env <COMMAND> ...
+        ```
 
-@cocoindex.main_fn()
-def main():
-  ...
+    *   If no file is found, only existing system environment variables are used.
+    *   Loaded variables do **not** override existing system ones.
 
-if __name__ == "__main__":
-  main()
-```
+2. **Automatic Library Initialization**:
+    *   Then, the CLI automatically prepares everything using loaded environment variables — no manual setup required.
+    *   Your script (e.g. `main.py`) is just used to discover defined flows.
 
-</TabItem>
-</Tabs>
+    See [Environment Variables](#environment-variables) for supported variables.
 
-This takes care of the following effects:
+    The primary way to interact with CocoIndex in this setup is via CLI commands that operate on your script:
+    You interact with CocoIndex via CLI commands that operate on your script:
 
-1.  Initialize the library with settings loaded from environment variables, if not explicitly provided.
-2.  If the program is executed with the `cocoindex` command, CocoIndex CLI will take over the control.
-    It provides a bunch of commands for easily managing and inspecting indexes.
-    See [CocoIndex CLI](/docs/core/cli) for more details.
-3.  Otherwise, it will run the main function.
+    ```sh
+    # Example: List flows defined in my_app.py
+    cocoindex ls my_app.py
 
-See [Environment Variables](#environment-variables) for supported environment variables.
+    # Example: Update a specific flow in my_app.py
+    cocoindex update my_app.py:MyFlowName
+    ```
 
+    See [CocoIndex CLI](/docs/core/cli) for more details.
 
 ### Explicit Initialization
 
@@ -123,7 +123,11 @@ If you use the Postgres database hosted by [Supabase](https://supabase.com/), pl
 
 ## Environment Variables
 
-When you use the packaged main function, settings will be loaded from environment variables.
+When using the CLI, settings are primarily loaded from environment variables. The CLI will:
+
+*   Use the `--env-file` option if provided.
+*   Otherwise, try to locate a `.env` file by searching upward from the current directory.
+
 Each setting field has a corresponding environment variable:
 
 | environment variable | corresponding field in `Settings` | required? |

docs/docs/getting_started/quickstart.md

@@ -46,19 +46,15 @@ We'll need to install a bunch of dependencies for this project.
 2.  Prepare input files for the index. Put them in a directory, e.g. `markdown_files`.
     If you don't have any files at hand, you may download the example [markdown_files.zip](markdown_files.zip) and unzip it in the current directory.
 
-## Step 2: Create the Python file `quickstart.py`
+## Step 2: Define the indexing flow
 
 Create a new file `quickstart.py` and import the `cocoindex` library:
 
 ```python title="quickstart.py"
 import cocoindex
 ```
 
-Then we'll create the indexing flow.
-
-### Step 2.1: Define the indexing flow
-
-Starting from the indexing flow:
+Then we'll create the indexing flow as follows.
 
 ```python title="quickstart.py"
 @cocoindex.flow_def(name="TextEmbedding")
@@ -117,24 +113,6 @@ Notes:
 
 6. In CocoIndex, a *collector* collects multiple entries of data together. In this example, the `doc_embeddings` collector collects data from all `chunk`s across all `doc`s, and using the collected data to build a vector index `"doc_embeddings"`, using `Postgres`.
 
-### Step 2.2: Define the main function
-
-We can provide an empty main function for now, with a `@cocoindex.main_fn()` decorator:
-
-```python title="quickstart.py"
-@cocoindex.main_fn()
-def _main():
-    pass
-
-if __name__ == "__main__":
-    _main()
-```
-
-The `@cocoindex.main_fn` declares a function as the main function for an indexing application. This achieves the following effects:
-
-*   Initialize the CocoIndex library states. Settings (e.g. database URL) are loaded from environment variables by default.
-*   When the CLI is invoked with `cocoindex` subcommand, `cocoindex CLI` takes over the control, which provides convenient ways to manage the index. See the next step for more details.
-
 ## Step 3: Run the indexing pipeline and queries
 
 Specify the database URL by environment variable:
@@ -148,7 +126,7 @@ export COCOINDEX_DATABASE_URL="postgresql://cocoindex:cocoindex@localhost:5432/c
 We need to setup the index:
 
 ```bash
-python quickstart.py cocoindex setup
+cocoindex setup quickstart.py
 ```
 
 Enter `yes` and it will automatically create a few tables in the database.
@@ -160,7 +138,7 @@ Now we have tables needed by this CocoIndex flow.
 Now we're ready to build the index:
 
 ```bash
-python quickstart.py cocoindex update
+cocoindex update quickstart.py
 ```
 
 It will run for a few seconds and output the following statistics:
@@ -260,13 +238,12 @@ There're two CocoIndex-specific logic:
     It's done by the `eval()` method of the transform flow `text_to_embedding`.
     The return type of this method is `list[float]` as declared in the `text_to_embedding()` function (`cocoindex.DataSlice[list[float]]`).
 
-### Step 4.3: Update the main function
+### Step 4.3: Add the main script logic
 
-Now we can update the main function to use the query function we just defined:
+Now we can add the main logic to the program. It uses the query function we just defined:
 
 ```python title="quickstart.py"
-@cocoindex.main_fn()
-def _run():
+if __name__ == "__main__":
     # Initialize the database connection pool.
     pool = ConnectionPool(os.getenv("COCOINDEX_DATABASE_URL"))
     # Run queries in a loop to demonstrate the query capabilities.
@@ -291,7 +268,7 @@ It interacts with users and search the database by calling the `search()` method
 
 ### Step 4.4: Run queries against the index
 
-Now we can run the same Python file, which will run the new main function:
+Now we can run the same Python file, which will run the new added main logic:
 
 ```bash
 python quickstart.py

examples/amazon_s3_embedding/main.py

@@ -1,5 +1,3 @@
-from dotenv import load_dotenv
-
 import cocoindex
 import os
 
@@ -52,7 +50,6 @@ def amazon_s3_text_embedding_flow(flow_builder: cocoindex.FlowBuilder, data_scop
             model="sentence-transformers/all-MiniLM-L6-v2")),
     default_similarity_metric=cocoindex.VectorSimilarityMetric.COSINE_SIMILARITY)
 
-@cocoindex.main_fn()
 def _run():
     # Use a `FlowLiveUpdater` to keep the flow data updated.
     with cocoindex.FlowLiveUpdater(amazon_s3_text_embedding_flow):
@@ -73,5 +70,4 @@ def _run():
                 break
 
 if __name__ == "__main__":
-    load_dotenv(override=True)
     _run()

examples/code_embedding/main.py

@@ -1,5 +1,3 @@
-from dotenv import load_dotenv
-
 import cocoindex
 import os
 
@@ -54,7 +52,6 @@ def code_embedding_flow(flow_builder: cocoindex.FlowBuilder, data_scope: cocoind
     query_transform_flow=code_to_embedding,
     default_similarity_metric=cocoindex.VectorSimilarityMetric.COSINE_SIMILARITY)
 
-@cocoindex.main_fn()
 def _run():
     # Run queries in a loop to demonstrate the query capabilities.
     while True:
@@ -73,5 +70,4 @@ def _run():
             break
 
 if __name__ == "__main__":
-    load_dotenv(override=True)
     _run()

examples/docs_to_knowledge_graph/main.py

@@ -2,7 +2,6 @@
 This example shows how to extract relationships from documents and build a knowledge graph.
 """
 import dataclasses
-from dotenv import load_dotenv
 import cocoindex
 
 @dataclasses.dataclass
@@ -148,10 +147,8 @@ def docs_to_kg_flow(flow_builder: cocoindex.FlowBuilder, data_scope: cocoindex.D
         primary_key_fields=["id"],
     )
 
-@cocoindex.main_fn()
 def _run():
     pass
 
 if __name__ == "__main__":
-    load_dotenv(override=True)
     _run()

examples/fastapi_server_docker/main.py

@@ -2,7 +2,6 @@
 import uvicorn
 
 from fastapi import FastAPI
-from dotenv import load_dotenv
 
 from src.cocoindex_funs import code_embedding_flow, code_to_embedding
 
@@ -21,10 +20,8 @@ def query_endpoint(string: str):
     results, _ = query_handler.search(string, 10)
     return results
 
-@cocoindex.main_fn()
 def _run():
     uvicorn.run(fastapi_app, host="0.0.0.0", port=8080)
 
 if __name__ == "__main__":
-    load_dotenv(override=True)
     _run()