Read-Only Mode

Read-only mode allows you to restrict pets to only perform read operations, preventing any accidental modifications to your data. When enabled, write tools (create, update, delete, etc.) are automatically filtered out and unavailable.

Why Use Read-Only Mode?

• Safety: Prevent accidental data modifications when exploring or auditing
• Compliance: Ensure certain environments can only read data
• Testing: Safely test pet connections without risk of changes
• Shared Access: Allow team members to view data without write permissions

Quick Start

Enable Read-Only for a Single Pet

# Enable read-only mode for the Asana pet
pets read-only asana on

# Disable read-only mode
pets read-only asana off

Enable Read-Only for All Pets

# Enable read-only mode globally
pets read-only --global on

# Disable global read-only mode
pets read-only --global off

Check Current Status

# Show read-only status for all pets
pets read-only --status

# Inspect the specific pet entry in the output above

Configuration Methods

Read-only mode can be configured in three ways, listed in priority order (highest first):

1. Environment Variables (Highest Priority)

Set an environment variable using the pattern {PETNAME}_READ_ONLY:

# In your shell
export ASANA_READ_ONLY=true
export JIRA_READ_ONLY=true
export GITHUB_READ_ONLY=true

# Or in your .env file
ASANA_READ_ONLY=true
JIRA_READ_ONLY=true

This method takes precedence over all other configurations.

2. CLI Command (Recommended)

Use the pets read-only command to configure per-project settings:

# Enable for a specific pet
pets read-only asana on

# Enable for all pets in the project
pets read-only --global on

This stores the configuration in .pets/config.json in your project directory.

3. Manual Configuration File

Edit .pets/config.json directly:

{
  "petConfig": {
    "asana": {
      "readOnly": true
    },
    "jira": {
      "readOnly": false
    },
    "_global": {
      "readOnly": false
    }
  }
}

• Use "_global" to set the default for all pets
• Pet-specific settings override the global setting
• Environment variables override both

How It Works

When a pet initializes, it checks for read-only mode using the SDK's isReadOnly() function:

1. Check environment variable: {PETNAME}_READ_ONLY
2. Check pet-specific config: .pets/config.json → petConfig.{petId}.readOnly
3. Check global config: .pets/config.json → petConfig._global.readOnly

If any of these return true, the pet filters out all write operations.

Which Tools Are Disabled?

Write operations are identified by patterns in the tool name. Common patterns include:

Pattern	Examples
create	asana-create-task, jira-create-issue
update	asana-update-task, github-update-pr
delete	asana-delete-task, jira-delete-comment
add-	asana-add-comment, github-add-label
remove-	asana-remove-tag, github-remove-assignee
move-	asana-move-task-to-section

Read operations (get, list, search) remain available:

Pattern	Examples
get-	asana-get-task, jira-get-issue
list-	asana-list-projects, github-list-repos
search	asana-search-tasks, jira-search
test-connection	asana-test-connection

Verifying Read-Only Status

Via CLI

$ pets read-only --status

🔒 Read-Only Mode Status
------------------------

⚙️  Global: not configured

📋 Pet-specific settings:
   🔒 asana: READ-ONLY
   🔓 jira: read-write

💡 Tip: Use "pets read-only <pet-name> on" to enable read-only mode

Via Test Connection

Most pets include read-only status in their test-connection output:

$ bun test:pet asana --query "test connection"

{
  "success": true,
  "status": "connected",
  "readOnlyMode": {
    "enabled": true,
    "message": "Read-only mode is ENABLED. Write operations are disabled."
  }
}

Examples

Scenario: Safe Exploration

You want to explore your Asana projects without risk of modifications:

# Enable read-only mode
pets read-only asana on

# Now you can safely explore
bun test:pet asana --query "list all my asana tasks"
bun test:pet asana --query "get details for task 123456"
bun test:pet asana --query "search for tasks assigned to me"

# These will NOT be available:
# - asana-create-task
# - asana-update-task
# - asana-delete-task
# - asana-add-comment

Scenario: Production Safety

For a production environment, enable global read-only:

# In your production .env file
echo "ASANA_READ_ONLY=true" >> .env
echo "JIRA_READ_ONLY=true" >> .env
echo "GITHUB_READ_ONLY=true" >> .env

Or use the CLI:

pets read-only --global on

Scenario: Mixed Permissions

Allow writes to Jira but read-only for everything else:

# Enable global read-only
pets read-only --global on

# Override for Jira only
pets read-only jira off

Result in .pets/config.json:

{
  "petConfig": {
    "_global": { "readOnly": true },
    "jira": { "readOnly": false }
  }
}

Scenario: Temporary Override via Environment

Your project has read-only enabled, but you need to make a quick update:

# Temporarily disable read-only for this session
ASANA_READ_ONLY=false bun test:pet asana --query "create a task called Test"

For Pet Developers

Implementing Read-Only Support

Use the SDK's helper functions to implement read-only mode:

import { 
  z, createPlugin, type ToolDefinition, createLogger, loadEnv,
  isReadOnly, filterToolsForReadOnly 
} from "openpets-sdk"

export const MyPlugin = async () => {
  const logger = createLogger("my-plugin")
  const env = loadEnv("my-plugin")
  
  // Check if read-only mode is enabled
  const readOnlyMode = isReadOnly("my-plugin")
  
  if (readOnlyMode) {
    logger.info("READ-ONLY MODE ENABLED - write operations disabled")
  }
  
  // Define patterns that identify write operations
  const WRITE_PATTERNS = ['create', 'update', 'delete', 'add-', 'remove-']
  
  // Build all your tools
  const allTools: ToolDefinition[] = [
    // Read tools (always available)
    { name: "my-plugin-list-items", ... },
    { name: "my-plugin-get-item", ... },
    { name: "my-plugin-search", ... },
    
    // Write tools (filtered in read-only mode)
    { name: "my-plugin-create-item", ... },
    { name: "my-plugin-update-item", ... },
    { name: "my-plugin-delete-item", ... },
  ]
  
  // Filter out write tools if in read-only mode
  const tools = filterToolsForReadOnly(
    allTools, 
    WRITE_PATTERNS, 
    readOnlyMode, 
    logger
  )
  
  return createPlugin(tools)
}

SDK Functions Reference

Function	Description
isReadOnly(petId)	Returns true if read-only mode is enabled
filterToolsForReadOnly(tools, patterns, isReadOnly, logger?)	Filters out write tools
setReadOnly(petId, enabled, projectDir?)	Programmatically set read-only mode
getReadOnlyStatus(petId?, projectDir?)	Get status for all pets

Best Practices

1. Always include test-connection - This should work in both modes
2. Log when read-only is active - Help users understand tool availability
3. Include status in test-connection response - Show current mode
4. Document disabled tools - List which tools are unavailable in read-only mode in your FAQ

Troubleshooting

Read-only mode not working

1. Check priority order: Environment variables override config files

   # Check for env override
   echo $ASANA_READ_ONLY
   
   # Check config
   pets read-only --status

2. Restart your session: Changes require restarting the active client session

   pets read-only asana on
   # Then restart your client session

3. Check the right directory: .pets/config.json is project-specific

   # Make sure you're in the right project
   pwd
   cat .pets/config.json

Can't disable read-only mode

If you've set an environment variable, it takes precedence:

# Remove the env variable
unset ASANA_READ_ONLY

# Or explicitly set to false
export ASANA_READ_ONLY=false

Write tools still showing

The pet may not have implemented read-only mode yet. Check:

1. Pet version - update to the latest
2. Pet documentation - see if read-only is supported
3. Test connection output - check if readOnlyMode is included

Related Documentation

• Configuration Guide - General configuration options
• Security Guide - Security best practices
• Best Practices - Pet development guidelines