Usage
All scripts can be executed using Node.js. Replace <param_name> and <param_value> with actual values.
Bash:
node <skill_dir>/scripts/<script_name>.js '{"<param_name>": "<param_value>"}'
PowerShell:
node <skill_dir>/scripts/<script_name>.js '{\"<param_name>\": \"<param_value>\"}'
Note: The scripts automatically load the environment variables from various .env files. Do not ask the user to set vars unless skill executions fails due to env var absence.
Scripts
add_documents
Adds a new document to a Firestore collection. Please follow the best practices :
- Always use typed values in the documentData: Every field must be wrapped with its appropriate type indicator (e.g., {"stringValue": "text"})
- Integer values can be strings in the documentData: The tool accepts integer values as strings (e.g., {"integerValue": "1500"})
- Use returnData sparingly: Only set to true when you need to verify the exact data that was written
- Validate data before sending: Ensure your data matches Firestore's native JSON format
- Handle timestamps properly: Use RFC3339 format for timestamp strings
- Base64 encode binary data: Binary data must be base64 encoded in the bytesValue field
- Consider security rules: Ensure your Firestore security rules allow document creation in the target collection
Parameters
| Name |
Type |
Description |
Required |
Default |
| collectionPath |
string |
The relative path of the collection where the document will be added to (e.g., 'users' or 'users/userId/posts'). Note: This is a relative path, NOT an absolute path like 'projects/{project_id}/databases/{database_id}/documents/...' |
Yes |
|
| documentData |
object |
The document data in Firestore's native JSON format. Each field must be wrapped with a type indicator: |
|
|
- Strings: {"stringValue": "text"}
- Integers: {"integerValue": "123"} or {"integerValue": 123}
- Doubles: {"doubleValue": 123.45}
- Booleans: {"booleanValue": true}
- Timestamps: {"timestampValue": "2025-01-07T10:00:00Z"}
- GeoPoints: {"geoPointValue": {"latitude": 34.05, "longitude": -118.24}}
- Arrays: {"arrayValue": {"values": [{"stringValue": "item1"}, {"integerValue": "2"}]}}
- Maps: {"mapValue": {"fields": {"key1": {"stringValue": "value1"}, "key2": {"booleanValue": true}}}}
- Null: {"nullValue": null}
- Bytes: {"bytesValue": "base64EncodedString"}
- References: {"referenceValue": "collection/document"} | Yes | |
| returnData | boolean | If set to true the output will have the data of the created document. This flag if set to false will help avoid overloading the context of the agent. | No |
false |
delete_documents
Delete multiple documents from Firestore
Parameters
| Name |
Type |
Description |
Required |
Default |
| documentPaths |
array |
Array of relative document paths to delete from Firestore (e.g., 'users/userId' or 'users/userId/posts/postId'). Note: These are relative paths, NOT absolute paths like 'projects/{project_id}/databases/{database_id}/documents/...' |
Yes |
|
get_documents
Gets multiple documents from Firestore by their paths
Parameters
| Name |
Type |
Description |
Required |
Default |
| documentPaths |
array |
Array of relative document paths to retrieve from Firestore (e.g., 'users/userId' or 'users/userId/posts/postId'). Note: These are relative paths, NOT absolute paths like 'projects/{project_id}/databases/{database_id}/documents/...' |
Yes |
|
list_collections
List Firestore collections for a given parent path
Parameters
| Name |
Type |
Description |
Required |
Default |
| parentPath |
string |
Relative parent document path to list subcollections from (e.g., 'users/userId'). If not provided, lists root collections. Note: This is a relative path, NOT an absolute path like 'projects/{project_id}/databases/{database_id}/documents/...' |
No |
|
query_collection
Retrieves one or more Firestore documents from a collection in a database in the current project by a collection with a full document path.
Use this if you know the exact path of a collection and the filtering clause you would like for the document.
Parameters
| Name |
Type |
Description |
Required |
Default |
| collectionPath |
string |
The relative path to the Firestore collection to query (e.g., 'users' or 'users/userId/posts'). Note: This is a relative path, NOT an absolute path like 'projects/{project_id}/databases/{database_id}/documents/...' |
Yes |
|
| filters |
array |
Array of filter objects to apply to the query. Each filter is a JSON string with: |
|
|
- field: The field name to filter on
- op: The operator to use ("<", "<=", ">", ">=", "==", "!=", "array-contains", "array-contains-any", "in", "not-in")
- value: The value to compare against (can be string, number, boolean, or array)
Example: {"field": "age", "op": ">", "value": 18} | Yes | |
| orderBy | string | JSON string specifying the field and direction to order by (e.g., {"field": "name", "direction": "ASCENDING"}). Leave empty if not specified | Yes | |
| limit | integer | The maximum number of documents to return | No |
100 |
| analyzeQuery | boolean | If true, returns query explain metrics including execution statistics | No | false |
update_document
Updates an existing document in Firestore. Supports both full document updates and selective field updates using an update mask. Please follow the best practices:
- Use update masks for precision: When you only need to update specific fields, use the updateMask parameter to avoid unintended changes
- Always use typed values in the documentData: Every field must be wrapped with its appropriate type indicator (e.g., {"stringValue": "text"})
- Delete fields using update mask: To delete fields, include them in the updateMask but omit them from documentData
- Integer values can be strings: The skill accepts integer values as strings (e.g., {"integerValue": "1500"})
- Use returnData sparingly: Only set to true when you need to verify the exact data after the update
- Handle timestamps properly: Use RFC3339 format for timestamp strings
- Consider security rules: Ensure your Firestore security rules allow document updates
Parameters
| Name |
Type |
Description |
Required |
Default |
| documentPath |
string |
The relative path of the document which needs to be updated (e.g., 'users/userId' or 'users/userId/posts/postId'). Note: This is a relative path, NOT an absolute path like 'projects/{project_id}/databases/{database_id}/documents/...' |
Yes |
|
| documentData |
object |
The document data in Firestore's native JSON format. Each field must be wrapped with a type indicator: |
|
|
- Strings: {"stringValue": "text"}
- Integers: {"integerValue": "123"} or {"integerValue": 123}
- Doubles: {"doubleValue": 123.45}
- Booleans: {"booleanValue": true}
- Timestamps: {"timestampValue": "2025-01-07T10:00:00Z"}
- GeoPoints: {"geoPointValue": {"latitude": 34.05, "longitude": -118.24}}
- Arrays: {"arrayValue": {"values": [{"stringValue": "item1"}, {"integerValue": "2"}]}}
- Maps: {"mapValue": {"fields": {"key1": {"stringValue": "value1"}, "key2": {"booleanValue": true}}}}
- Null: {"nullValue": null}
- Bytes: {"bytesValue": "base64EncodedString"}
- References: {"referenceValue": "collection/document"} | Yes | |
| updateMask | array | The selective fields to update. If not provided, all fields in documentData will be updated. When provided, only the specified fields will be updated. Fields referenced in the mask but not present in documentData will be deleted from the document | No | |
| returnData | boolean | If set to true the output will have the data of the updated document. This flag if set to false will help avoid overloading the context of the agent. | No |
false |
1---2name: firestore-data3description: Handles NoSQL document operations and collection hierarchy exploration. Use for CRUD tasks and data retrieval. Provides flexible document manipulation and structured querying.4---5
6## Usage
7
8All scripts can be executed using Node.js. Replace `<param_name>` and `<param_value>` with actual values.
9
10**Bash:**
11`node <skill_dir>/scripts/<script_name>.js '{"<param_name>": "<param_value>"}'`
12
13**PowerShell:**
14`node <skill_dir>/scripts/<script_name>.js '{\"<param_name>\": \"<param_value>\"}'`
15
16Note: The scripts automatically load the environment variables from various .env files. Do not ask the user to set vars unless skill executions fails due to env var absence.
17
18
19## Scripts
20
21
22### add_documents
23
24Adds a new document to a Firestore collection. Please follow the best practices :
25 1. Always use typed values in the documentData: Every field must be wrapped with its appropriate type indicator (e.g., {"stringValue": "text"})
26 2. Integer values can be strings in the documentData: The tool accepts integer values as strings (e.g., {"integerValue": "1500"})
27 3. Use returnData sparingly: Only set to true when you need to verify the exact data that was written
28 4. Validate data before sending: Ensure your data matches Firestore's native JSON format
29 5. Handle timestamps properly: Use RFC3339 format for timestamp strings
30 6. Base64 encode binary data: Binary data must be base64 encoded in the bytesValue field
31 7. Consider security rules: Ensure your Firestore security rules allow document creation in the target collection
32
33
34#### Parameters
35
36| Name | Type | Description | Required | Default |
37| :--- | :--- | :--- | :--- | :--- |
38| collectionPath | string | The relative path of the collection where the document will be added to (e.g., 'users' or 'users/userId/posts'). Note: This is a relative path, NOT an absolute path like 'projects/{project_id}/databases/{database_id}/documents/...' | Yes | |
39| documentData | object | The document data in Firestore's native JSON format. Each field must be wrapped with a type indicator:
40- Strings: {"stringValue": "text"}
41- Integers: {"integerValue": "123"} or {"integerValue": 123}
42- Doubles: {"doubleValue": 123.45}
43- Booleans: {"booleanValue": true}
44- Timestamps: {"timestampValue": "2025-01-07T10:00:00Z"}
45- GeoPoints: {"geoPointValue": {"latitude": 34.05, "longitude": -118.24}}
46- Arrays: {"arrayValue": {"values": [{"stringValue": "item1"}, {"integerValue": "2"}]}}
47- Maps: {"mapValue": {"fields": {"key1": {"stringValue": "value1"}, "key2": {"booleanValue": true}}}}
48- Null: {"nullValue": null}
49- Bytes: {"bytesValue": "base64EncodedString"}
50- References: {"referenceValue": "collection/document"} | Yes | |
51| returnData | boolean | If set to true the output will have the data of the created document. This flag if set to false will help avoid overloading the context of the agent. | No | `false` |
52
53
54---
55
56### delete_documents
57
58Delete multiple documents from Firestore
59
60#### Parameters
61
62| Name | Type | Description | Required | Default |
63| :--- | :--- | :--- | :--- | :--- |
64| documentPaths | array | Array of relative document paths to delete from Firestore (e.g., 'users/userId' or 'users/userId/posts/postId'). Note: These are relative paths, NOT absolute paths like 'projects/{project_id}/databases/{database_id}/documents/...' | Yes | |
65
66
67---
68
69### get_documents
70
71Gets multiple documents from Firestore by their paths
72
73#### Parameters
74
75| Name | Type | Description | Required | Default |
76| :--- | :--- | :--- | :--- | :--- |
77| documentPaths | array | Array of relative document paths to retrieve from Firestore (e.g., 'users/userId' or 'users/userId/posts/postId'). Note: These are relative paths, NOT absolute paths like 'projects/{project_id}/databases/{database_id}/documents/...' | Yes | |
78
79
80---
81
82### list_collections
83
84List Firestore collections for a given parent path
85
86#### Parameters
87
88| Name | Type | Description | Required | Default |
89| :--- | :--- | :--- | :--- | :--- |
90| parentPath | string | Relative parent document path to list subcollections from (e.g., 'users/userId'). If not provided, lists root collections. Note: This is a relative path, NOT an absolute path like 'projects/{project_id}/databases/{database_id}/documents/...' | No | |
91
92
93---
94
95### query_collection
96
97Retrieves one or more Firestore documents from a collection in a database in the current project by a collection with a full document path.
98Use this if you know the exact path of a collection and the filtering clause you would like for the document.
99
100
101#### Parameters
102
103| Name | Type | Description | Required | Default |
104| :--- | :--- | :--- | :--- | :--- |
105| collectionPath | string | The relative path to the Firestore collection to query (e.g., 'users' or 'users/userId/posts'). Note: This is a relative path, NOT an absolute path like 'projects/{project_id}/databases/{database_id}/documents/...' | Yes | |
106| filters | array | Array of filter objects to apply to the query. Each filter is a JSON string with:
107- field: The field name to filter on
108- op: The operator to use ("<", "<=", ">", ">=", "==", "!=", "array-contains", "array-contains-any", "in", "not-in")
109- value: The value to compare against (can be string, number, boolean, or array)
110Example: {"field": "age", "op": ">", "value": 18} | Yes | |
111| orderBy | string | JSON string specifying the field and direction to order by (e.g., {"field": "name", "direction": "ASCENDING"}). Leave empty if not specified | Yes | |
112| limit | integer | The maximum number of documents to return | No | `100` |
113| analyzeQuery | boolean | If true, returns query explain metrics including execution statistics | No | `false` |
114
115
116---
117
118### update_document
119
120Updates an existing document in Firestore. Supports both full document updates and selective field updates using an update mask. Please follow the best practices:
121 1. Use update masks for precision: When you only need to update specific fields, use the updateMask parameter to avoid unintended changes
122 2. Always use typed values in the documentData: Every field must be wrapped with its appropriate type indicator (e.g., {"stringValue": "text"})
123 3. Delete fields using update mask: To delete fields, include them in the updateMask but omit them from documentData
124 4. Integer values can be strings: The skill accepts integer values as strings (e.g., {"integerValue": "1500"})
125 5. Use returnData sparingly: Only set to true when you need to verify the exact data after the update
126 6. Handle timestamps properly: Use RFC3339 format for timestamp strings
127 7. Consider security rules: Ensure your Firestore security rules allow document updates
128
129
130#### Parameters
131
132| Name | Type | Description | Required | Default |
133| :--- | :--- | :--- | :--- | :--- |
134| documentPath | string | The relative path of the document which needs to be updated (e.g., 'users/userId' or 'users/userId/posts/postId'). Note: This is a relative path, NOT an absolute path like 'projects/{project_id}/databases/{database_id}/documents/...' | Yes | |
135| documentData | object | The document data in Firestore's native JSON format. Each field must be wrapped with a type indicator:
136- Strings: {"stringValue": "text"}
137- Integers: {"integerValue": "123"} or {"integerValue": 123}
138- Doubles: {"doubleValue": 123.45}
139- Booleans: {"booleanValue": true}
140- Timestamps: {"timestampValue": "2025-01-07T10:00:00Z"}
141- GeoPoints: {"geoPointValue": {"latitude": 34.05, "longitude": -118.24}}
142- Arrays: {"arrayValue": {"values": [{"stringValue": "item1"}, {"integerValue": "2"}]}}
143- Maps: {"mapValue": {"fields": {"key1": {"stringValue": "value1"}, "key2": {"booleanValue": true}}}}
144- Null: {"nullValue": null}
145- Bytes: {"bytesValue": "base64EncodedString"}
146- References: {"referenceValue": "collection/document"} | Yes | |
147| updateMask | array | The selective fields to update. If not provided, all fields in documentData will be updated. When provided, only the specified fields will be updated. Fields referenced in the mask but not present in documentData will be deleted from the document | No | |
148| returnData | boolean | If set to true the output will have the data of the updated document. This flag if set to false will help avoid overloading the context of the agent. | No | `false` |
149
150
151---
152
cline