|
3 | 3 |
|
4 | 4 |
|
5 | 5 |
|
6 | | -Needlectl is a command-line tool designed to interact with **Needle**, a system that retrieves and manages visual content. This CLI enables you to efficiently manage directories, perform searches, and control backend services—all through a simple and powerful interface. |
| 6 | +Needlectl is a command-line tool designed to interact with **Needle**, a system that retrieves and manages visual content. This CLI enables you to efficiently manage directories, perform searches, and control backend services—all through a simple and powerful interface. Checkout the [Documenation](https://uic-indexlab.github.io/Needle/needlectl/index.html) for more details. |
7 | 7 |
|
8 | 8 | --- |
9 | 9 |
|
10 | | -## 🎯 Goal |
11 | | - |
12 | | -Needlectl provides an intuitive way to manage the Needle system, allowing users to: |
13 | | -- Add, remove, and list directories containing image datasets. |
14 | | -- Run advanced search queries on visual data. |
15 | | -- Start, stop, and restart Needle's backend services with ease. |
16 | | - |
17 | | -It’s a seamless bridge between Needle’s backend and your data management needs. |
18 | | - |
19 | | ---- |
20 | | - |
21 | | -## 🌟 Key Capabilities |
22 | | - |
23 | | -### 🗂️ Directory Management |
24 | | -Organize your image datasets by adding or removing directories. Monitor indexing progress and retrieve detailed information about managed directories. |
25 | | - |
26 | | -Commands: |
27 | | -- **`directory add`**: Add a new directory to Needle. |
28 | | -- **`directory remove`**: Remove an existing directory. |
29 | | -- **`directory list`**: List all indexed directories. |
30 | | -- **`directory describe`**: Get detailed information about a specific directory. |
31 | | - |
32 | | -### 🔍 Search |
33 | | -Perform advanced searches for visual content using natural language prompts. Customize your search with options like the number of results, clustering size, and output image size. |
34 | | - |
35 | | -Commands: |
36 | | -- **`search run`**: Execute a search query and retrieve results. |
37 | | - |
38 | | -### ⚙️ Service Control |
39 | | -Control Needle's backend services, ensuring a smooth and reliable operation. |
40 | | - |
41 | | -Commands: |
42 | | -- **`service start`**: Start the Needle backend services. |
43 | | -- **`service stop`**: Stop the Needle backend services. |
44 | | -- **`service restart`**: Restart Needle’s services. |
45 | | - |
46 | | ---- |
47 | | - |
48 | | -## 🚀 How It Works |
49 | | - |
50 | | -### CLI Structure |
51 | | -The CLI has three primary groups of commands: |
52 | | -1. **Directory Commands**: Manage directories for Needle’s backend. |
53 | | -2. **Search Commands**: Execute searches for visual content. |
54 | | -3. **Service Commands**: Control Needle’s backend services. |
55 | | - |
56 | | -### Options |
57 | | -Global options available across all commands: |
58 | | -- **`--api-url`**: URL of the Needle backend API (default: `http://127.0.0.1:8000`). |
59 | | -- **`--output`**: Specify the output format (`human`, `json`, or `yaml`). |
60 | | - |
61 | | -### Output Formats |
62 | | -Needlectl supports multiple output formats to suit different use cases: |
63 | | -- **Human-readable** (default): For everyday usage in the terminal. |
64 | | -- **JSON/YAML**: Structured formats for integration with other tools or scripts. |
65 | | - |
66 | | ---- |
67 | | - |
68 | | -## 📖 Command Reference |
69 | | - |
70 | | -### 🗂️ Directory Management |
71 | | - |
72 | | -#### **`directory add`** |
73 | | -Add a directory to Needle. |
74 | | -```bash |
75 | | -needlectl directory add <path> [--show-progress] |
76 | | -``` |
77 | | -Options: |
78 | | -- **`<path>`**: Path to the directory to add. |
79 | | -- **`--show-progress`**: Display real-time indexing progress. |
80 | | - |
81 | | ---- |
82 | | - |
83 | | -#### **`directory remove`** |
84 | | -Remove a directory from Needle. |
85 | | -```bash |
86 | | -needlectl directory remove <path> |
87 | | -``` |
88 | | -Options: |
89 | | -- **`<path>`**: Path to the directory to remove. |
90 | | - |
91 | | ---- |
92 | | - |
93 | | -#### **`directory list`** |
94 | | -List all managed directories. |
95 | | -```bash |
96 | | -needlectl directory list |
97 | | -``` |
98 | | - |
99 | | ---- |
100 | | - |
101 | | -#### **`directory describe`** |
102 | | -Get detailed information about a specific directory. |
103 | | -```bash |
104 | | -needlectl directory describe <directory_id> |
105 | | -``` |
106 | | -Options: |
107 | | -- **`<directory_id>`**: The ID of the directory to describe. |
108 | | - |
109 | | ---- |
110 | | - |
111 | | -### 🔍 Search |
112 | | - |
113 | | -#### **`search run`** |
114 | | -Perform a search using a natural language prompt. |
115 | | -```bash |
116 | | -needlectl search run <query> [--n <int>] [--k <int>] [--image-size <int>] [--include-base-images] |
117 | | -``` |
118 | | -Options: |
119 | | -- **`--n`**: Number of results to return (default: `20`). |
120 | | -- **`--k`**: Number of base (guide) images to generate (default: `4`). |
121 | | -- **`--image-size`**: Size of the generated base images in pixels (default: `512`). |
122 | | -- **`--include-base-images`**: Include base images in the results. |
123 | | - |
124 | | ---- |
125 | | - |
126 | | -### ⚙️ Service Control |
127 | | - |
128 | | -#### **`service start`** |
129 | | -Start Needle backend services. |
130 | | -```bash |
131 | | -needlectl service start |
132 | | -``` |
133 | | - |
134 | | ---- |
135 | | - |
136 | | -#### **`service stop`** |
137 | | -Stop Needle backend services. |
138 | | -```bash |
139 | | -needlectl service stop |
140 | | -``` |
141 | | - |
142 | | ---- |
143 | | - |
144 | | -#### **`service restart`** |
145 | | -Restart Needle backend services. |
146 | | -```bash |
147 | | -needlectl service restart |
148 | | -``` |
149 | | - |
150 | | ---- |
151 | | - |
152 | | -## 💡 Examples |
153 | | - |
154 | | -1. Add a directory and show indexing progress: |
155 | | - ```bash |
156 | | - needlectl directory add /path/to/images --show-progress |
157 | | - ``` |
158 | | - |
159 | | -2. Perform a search query with 10 results and 2 1024x1024 pixel images: |
160 | | - ```bash |
161 | | - needlectl search run "sunset over mountains" --n 10 --image-size 1024 --k 2 |
162 | | - ``` |
163 | | - |
164 | | -3. Restart Needle services: |
165 | | - ```bash |
166 | | - needlectl service restart |
167 | | - ``` |
168 | | - |
169 | | -4. List all directories in human-readable format: |
170 | | - ```bash |
171 | | - needlectl directory list --output human |
172 | | - ``` |
173 | | - |
174 | | ---- |
175 | | - |
176 | | -⚙️ **Empower your workflows with Needlectl!** |
0 commit comments