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 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
• Few-shot prompts and command examples: examples.md
• Error handling and diagnostics: troubleshooting.md

Requirements

This skill requires curl and gcloud CLI.

For full installation and setup instructions, see 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:

ACCESS_TOKEN=$(gcloud auth print-access-token)

Before any operation, verify the active identity is a service account:

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:

   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:

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

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.