firestore

Original source / Raw SKILL.md

---
name: firestore
description: Manage Google Cloud Firestore databases using the Firestore REST API via curl commands. Authenticate using gcloud CLI tokens to perform CRUD operations on documents and collections.
user-invocable: true
disable-model-invocation: true
metadata: {"clawdbot":{"emoji":"🔥","requires":{"bins":["curl","gcloud"]},"install":[{"id":"gcloud-sdk","kind":"manual","url":"https://docs.cloud.google.com/sdk/docs/install-sdk","bins":["gcloud"],"label":"Install Google Cloud CLI (official)"}]}}
---

# Firestore
Manage Google Cloud Firestore databases via REST API

This skill is built on top of the official Firebase Firestore REST API reference documentation: https://firebase.google.com/docs/firestore/reference/rest

It enables you to interact with Google Cloud Firestore using the [Firestore REST API](https://firebase.google.com/docs/firestore/reference/rest) through `curl` commands. It uses `gcloud auth print-access-token` to obtain authentication tokens, allowing you to perform Create, Read, Update, and Delete (CRUD) operations on Firestore documents and collections.

For related documentation:
- Installation and setup: [installation.md](installation.md)
- Few-shot prompts and command examples: [examples.md](examples.md)
- Error handling and diagnostics: [troubleshooting.md](troubleshooting.md)

## Requirements

This skill requires `curl` and `gcloud` CLI.

For full installation and setup instructions, see [installation.md](installation.md).

## Credentials & Environment

This skill uses OAuth 2.0 access tokens generated by `gcloud auth print-access-token`. The token is valid for a limited time (typically 1 hour) and inherits the permissions of the authenticated Google Cloud account.

This skill must run only with a dedicated service account context. Do not use personal user credentials or broad admin identities.

**Before any operation, generate a fresh access token:**
```bash
ACCESS_TOKEN=$(gcloud auth print-access-token)
```

**Before any operation, verify the active identity is a service account:**
```bash
gcloud config list --format='text(core.account,core.project)'
```

If the active account is not a service account (for example, it does not end with `gserviceaccount.com`), stop and ask the user to switch credentials before proceeding.

**Security Recommendations:**
- **Use a dedicated, least-privilege service account** for automation tasks. Never use your personal or admin account.
- **Test in a sandbox or development project** before running commands against production.
- **Verify your active project** with `gcloud config list` before executing commands.
- **Tokens expire after approximately 1 hour** — regenerate if you encounter 401 Unauthorized errors.
- **The token inherits ALL permissions** of the authenticated account, including read access to sensitive data.
- **Revoke tokens immediately** if you suspect unauthorized access: `gcloud auth revoke`
- **Audit activity regularly** by reviewing Cloud Audit Logs for the project.

## Security Considerations

**Important:** This skill can access Firestore data with the same permissions as the authenticated Google Cloud account. For safety, this skill requires explicit user approval before executing any operation, including read-only operations.

**To minimize risk:**
1. Only use this skill with service accounts that have the minimum required Firestore permissions
2. Use separate projects for development/testing and production environments
3. Review the `gcloud config list` output before allowing any operations
4. Grant only `roles/datastore.viewer` for read-only access or `roles/datastore.user` for limited read/write
5. Never use `roles/datastore.owner` or `roles/owner` with this skill
6. Monitor Cloud Audit Logs for unexpected Firestore API calls

## What You Can Do

You can perform the following operations on Firestore databases:

- **Create** — Insert new documents into collections
- **Read** — Query documents with filters and conditions
- **Update** — Modify specific fields in existing documents using updateMask
- **Delete** — Remove documents from collections
- **List** — Retrieve all documents in a collection
- **Batch operations** — Perform multiple writes in a single atomic transaction

All operations use the Firestore REST API endpoint:
```
https://firestore.googleapis.com/v1/projects/{PROJECT_ID}/databases/{DATABASE_ID}/documents
```

## Workflow

Before executing any Firestore operation, you **MUST** follow this workflow:

1. **Check active context** — Run `gcloud config list --format='text(core.account,core.project)'` to display the active account and project. Present this to the user so they are aware of which credentials and project will be used.

2. **Generate access token** — Always start by obtaining a fresh access token:
   ```bash
   ACCESS_TOKEN=$(gcloud auth print-access-token)
   ```

3. **Construct the curl command** — Build the appropriate curl command based on the operation:
   - Use the correct HTTP method (POST for create/query, GET for read, PATCH for update, DELETE for delete)
   - Include the `Authorization: Bearer $ACCESS_TOKEN` header
   - Set `Content-Type: application/json` for requests with body
   - Use the correct API endpoint for the project and collection

4. **For all operations (read and write)** — Present the full curl command to the user and **wait for explicit approval** before executing. See the Approval Policy section below.

5. **Execute the command** and parse the JSON response.

## Important Rules

- **Always generate a fresh token first** — Run `ACCESS_TOKEN=$(gcloud auth print-access-token)` before any operation.
- **Use proper JSON formatting** — Firestore requires specific field value types (stringValue, booleanValue, integerValue, etc.).
- **Document ID generation** — When creating documents, if you don't specify `?documentId=YOUR_ID` in the URL, Firestore will automatically generate a unique document ID.
- **Include field paths in updateMask** — When updating, use `updateMask.fieldPaths` to specify which fields to update.
- **Never execute any command autonomously** — always present the full curl command to the user and wait for explicit approval before running it, including read-only operations.
- **Parse responses carefully** — Firestore returns data in a nested format with typed values.
- **Verify project ID** — Always confirm you're targeting the correct project before executing commands.

## Approval Policy

All operations require explicit user confirmation before execution.

This includes:
- **Create** — Creating new documents in collections
- **Read / Query / Get / List** — Retrieving documents or query results
- **Update / Patch** — Modifying existing document fields
- **Delete** — Removing documents permanently
- **Batch writes** — Any batch operation that modifies data

For every operation, the agent must:
1. Show the full curl command that will be executed.
2. Display the active account and project context.
3. Wait for the user to explicitly approve before running the command.

## Firestore Data Types

Firestore uses typed field values in JSON. Common types:

- `stringValue` — Text strings
- `integerValue` — Integer numbers (as strings)
- `doubleValue` — Floating-point numbers
- `booleanValue` — true/false
- `timestampValue` — ISO 8601 timestamps
- `arrayValue` — Arrays of values
- `mapValue` — Nested objects

Example document structure:
```json
{
  "fields": {
    "name": { "stringValue": "John Doe" },
    "age": { "integerValue": "30" },
    "active": { "booleanValue": true }
  }
}
```

## Few-Shot Prompting Examples

Few-shot prompts and full command examples are available in [examples.md](examples.md).

## Common Query Operators

When constructing queries, use these operators in the `fieldFilter.op` field:

- `EQUAL` — Field equals value
- `NOT_EQUAL` — Field does not equal value
- `LESS_THAN` — Field is less than value
- `LESS_THAN_OR_EQUAL` — Field is less than or equal to value
- `GREATER_THAN` — Field is greater than value
- `GREATER_THAN_OR_EQUAL` — Field is greater than or equal to value
- `ARRAY_CONTAINS` — Array field contains value
- `IN` — Field value is in the provided array
- `ARRAY_CONTAINS_ANY` — Array field contains any of the provided values

## Troubleshooting

For dedicated troubleshooting guidance, see [troubleshooting.md](troubleshooting.md).


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### installation.md

```markdown
# Firestore Installation

## Requirements

This skill requires two command-line tools to be installed:

1. **curl** - for making HTTP requests to the Firestore REST API
2. **gcloud CLI** - for authentication token generation

## Install and Verify

### curl

`curl` is typically pre-installed on macOS and most Linux distributions.

Verify installation:
```bash
curl --version
```

### Google Cloud CLI

Install from the official Google Cloud SDK documentation:
https://docs.cloud.google.com/sdk/docs/install-sdk

Verify installation:
```bash
gcloud --version
```

## Authenticate and Configure Project

After installation, authenticate and set the active project:
```bash
gcloud auth login
gcloud config set project YOUR_PROJECT_ID
```

Check active account and project:
```bash
gcloud config list --format='text(core.account,core.project)'
```

## Access Token

Before any Firestore API request, generate a fresh access token:
```bash
ACCESS_TOKEN=$(gcloud auth print-access-token)
```

The token is short-lived (typically around 1 hour). Regenerate it if requests return `401 Unauthorized`.

```

### examples.md

```markdown
# Firestore Examples

## Few-Shot Prompting Examples

All examples below follow this policy: present the full command and wait for explicit user approval before execution, including read-only operations.

### Example 1: Creating a new document

**User prompt:** "Create a user document with first_name John, last_name Doe, and is_active true in the users collection"

**Expected agent behavior:**
1. Run `gcloud config list --format='text(core.account,core.project)'` and show the active context to the user
2. Get the project ID from the output (e.g., `my-project`)
3. Construct the curl command:
   ```bash
   ACCESS_TOKEN=$(gcloud auth print-access-token)

   curl -X POST \
     -H "Authorization: Bearer $ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "fields": {
         "first_name": { "stringValue": "John" },
         "last_name": { "stringValue": "Doe" },
         "is_active": { "booleanValue": true }
       }
     }' \
     "https://firestore.googleapis.com/v1/projects/my-project/databases/(default)/documents/users"
   ```
4. Present the command to the user
5. **Wait for user approval** before executing (this is a create operation)

**Note:** When creating a document without specifying a `documentId` parameter in the URL, Firestore automatically generates a unique document ID. To create a document with a specific ID, append `?documentId=YOUR_ID` to the URL (see Example 5).

### Example 2: Querying documents with a filter

**User prompt:** "Find all users where first_name equals John"

**Expected agent behavior:**
1. Run `gcloud config list --format='text(core.account,core.project)'` and show the active context to the user
2. Get the project ID from the output
3. Construct the query curl command:
   ```bash
   ACCESS_TOKEN=$(gcloud auth print-access-token)

   curl -X POST \
     -H "Authorization: Bearer $ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "structuredQuery": {
         "from": [{"collectionId": "users"}],
         "where": {
           "fieldFilter": {
             "field": {"fieldPath": "first_name"},
             "op": "EQUAL",
             "value": {"stringValue": "John"}
           }
         }
       }
     }' \
     "https://firestore.googleapis.com/v1/projects/my-project/databases/(default)/documents:runQuery"
   ```
4. Present the command to the user
5. **Wait for user approval** before executing (this is a read operation)
6. Parse and present the results to the user

### Example 3: Updating specific fields in a document

**User prompt:** "Update the user document admin_test_01 to change last_name to Smith and set is_active to false"

**Expected agent behavior:**
1. Run `gcloud config list --format='text(core.account,core.project)'` and show the active context to the user
2. Get the project ID from the output
3. Construct the update curl command with updateMask:
   ```bash
   ACCESS_TOKEN=$(gcloud auth print-access-token)

   curl -X PATCH \
     -H "Authorization: Bearer $ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "fields": {
         "last_name": { "stringValue": "Smith" },
         "is_active": { "booleanValue": false }
       }
     }' \
     "https://firestore.googleapis.com/v1/projects/my-project/databases/(default)/documents/users/admin_test_01?updateMask.fieldPaths=last_name&updateMask.fieldPaths=is_active"
   ```
4. Present the command to the user
5. **Wait for user approval** before executing (this is an update operation)

### Example 4: Deleting a document

**User prompt:** "Delete the user document admin_test_01"

**Expected agent behavior:**
1. Run `gcloud config list --format='text(core.account,core.project)'` and show the active context to the user
2. Get the project ID from the output
3. Construct the delete curl command:
   ```bash
   ACCESS_TOKEN=$(gcloud auth print-access-token)

   curl -X DELETE \
     -H "Authorization: Bearer $ACCESS_TOKEN" \
     "https://firestore.googleapis.com/v1/projects/my-project/databases/(default)/documents/users/admin_test_01"
   ```
4. Present the command to the user
5. **Wait for user approval** before executing (this is a delete operation)

### Example 5: Creating a document with a specific ID

**User prompt:** "Create a settings document with ID app_config containing theme as dark and notifications enabled"

**Expected agent behavior:**
1. Run `gcloud config list --format='text(core.account,core.project)'` and show the active context to the user
2. Get the project ID from the output
3. Construct the curl command with documentId parameter:
   ```bash
   ACCESS_TOKEN=$(gcloud auth print-access-token)

   curl -X POST \
     -H "Authorization: Bearer $ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "fields": {
         "theme": { "stringValue": "dark" },
         "notifications": { "booleanValue": true }
       }
     }' \
     "https://firestore.googleapis.com/v1/projects/my-project/databases/(default)/documents/settings?documentId=app_config"
   ```
4. Present the command to the user
5. **Wait for user approval** before executing (this is a create operation)

## Common Query Operators

When constructing queries, use these operators in the `fieldFilter.op` field:

- `EQUAL` - Field equals value
- `NOT_EQUAL` - Field does not equal value
- `LESS_THAN` - Field is less than value
- `LESS_THAN_OR_EQUAL` - Field is less than or equal to value
- `GREATER_THAN` - Field is greater than value
- `GREATER_THAN_OR_EQUAL` - Field is greater than or equal to value
- `ARRAY_CONTAINS` - Array field contains value
- `IN` - Field value is in the provided array
- `ARRAY_CONTAINS_ANY` - Array field contains any of the provided values

```

### troubleshooting.md

```markdown
# Firestore Troubleshooting

## 401 Unauthorized

- Token expired. Regenerate with:
  ```bash
  ACCESS_TOKEN=$(gcloud auth print-access-token)
  ```
- Incorrect authentication. Re-authenticate:
  ```bash
  gcloud auth login
  ```
- Validate active account and project:
  ```bash
  gcloud config list --format='text(core.account,core.project)'
  ```

## 403 Forbidden

- Insufficient IAM permissions for the authenticated identity.
- Firestore API is not enabled in the target project.
- Verify role assignment and project context before retrying.

## 404 Not Found

- Incorrect project ID, database ID, collection path, or document path.
- Requested collection or document does not exist.
- Confirm the endpoint path format:
  ```text
  /v1/projects/{PROJECT_ID}/databases/{DATABASE_ID}/documents/{COLLECTION}/{DOCUMENT_ID}
  ```

## 400 Bad Request

- Invalid JSON payload format.
- Invalid Firestore field types (for example, using `stringValue` where `integerValue` is expected).
- Missing required request body fields.
- Incorrect query structure for `documents:runQuery`.

## Update Errors

- Missing `updateMask.fieldPaths` when partially updating documents.
- Updating a path that does not exist.
- Using invalid field path names in update masks.

## Quick Debug Checklist

1. Confirm active context:
   ```bash
   gcloud config list --format='text(core.account,core.project)'
   ```
2. Refresh token:
   ```bash
   ACCESS_TOKEN=$(gcloud auth print-access-token)
   ```
3. Test API reachability with a simple read request.
4. Validate JSON payload with a linter before sending.
5. Recheck IAM roles and Firestore API enablement.

```



---

## Skill Companion Files

> Additional files collected from the skill directory layout.

### _meta.json

```json
{
  "owner": "felipe0liveira",
  "slug": "firestore",
  "displayName": "Firestore",
  "latest": {
    "version": "1.0.4",
    "publishedAt": 1772822802683,
    "commit": "https://github.com/openclaw/skills/commit/2d577de13033bc7d05946cd1a4d90301ad34711c"
  },
  "history": []
}

```