# Firestore

> 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.

- Skill: `dvcrn/firestore` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add dvcrn/firestore`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dvcrn/firestore/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: dvcrn (https://skillmd.com/u/dvcrn)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/dvcrn/firestore

---


# 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).