Where Are IPATool's Cookies Stored? Cache Paths and Implementation Explained

IPATool stores its HTTP cookies in a persistent JSON file named cookies.json located in the platform-specific user cache directory, enabling session reuse across multiple command invocations without re-authentication.

When you authenticate with Apple's App Store using the ipatool CLI, the tool maintains your session state in a persistent cookie jar. Understanding where IPATool's cookies are stored helps with troubleshooting authentication issues, clearing stale sessions, or backing up login credentials. The implementation resides in the majd/ipatool repository, specifically within the pkg/http package.

Cookie Storage Location by Operating System

IPATool determines the storage path using Go's os.UserCacheDir() function, which returns platform-appropriate cache directories. The tool creates an ipatool subdirectory and writes the cookie data to cookies.json.

macOS

On macOS systems, IPATool's cookies are stored in the Library Caches directory:

~/Library/Caches/ipatool/cookies.json

Linux

For Linux distributions following the XDG Base Directory Specification, the path resolves to:

~/.cache/ipatool/cookies.json

Windows

On Windows, the cache directory uses the LocalAppData folder:

%LocalAppData%\ipatool\Cache\cookies.json

How IPATool Persists Cookies (Implementation Details)

The cookie persistence mechanism relies on three key components in the source code. In pkg/http/cookiejar.go, the codebase defines a CookieJar interface that extends Go's standard http.CookieJar with a Save() error method. The concrete implementation in pkg/http/cookiejar_impl.go handles JSON serialization and filesystem operations.

When the HTTP client initializes via NewPersistentCookieJar(), it loads any existing cookies from disk into memory. During operation, the client defined in pkg/http/client.go invokes c.cookieJar.Save() after each request completes, ensuring the cookie jar remains synchronized with the filesystem.

// pkg/http/client.go (simplified workflow)
func (c *Client) do(req *http.Request) (*http.Response, error) {
    resp, err := c.http.Do(req)
    if err != nil {
        return nil, err
    }
    // Persist cookies immediately after request completion
    _ = c.cookieJar.Save()
    return resp, nil
}

The cookies.json file contains a JSON-encoded slice of http.Cookie objects. This format allows IPATool to preserve authentication tokens, session IDs, and other HTTP state information between separate process executions.

Inspecting and Clearing Stored Cookies

You can manually inspect the current cookie state or clear authentication data by manipulating the cookies.json file directly.

To view stored cookies on macOS:

cat ~/Library/Caches/ipatool/cookies.json

To clear all stored cookies and force re-authentication:

rm ~/Library/Caches/ipatool/cookies.json

Replace the path with the appropriate location for your operating system. Deleting this file removes all session state, requiring you to log in again on the next IPATool invocation.

Summary

• IPATool stores cookies in cookies.json within the user cache directory (~/Library/Caches/ipatool/ on macOS, ~/.cache/ipatool/ on Linux, %LocalAppData%\ipatool\Cache\ on Windows).
• The CookieJar interface in pkg/http/cookiejar.go defines the Save() method contract for persistence.
• The implementation in pkg/http/cookiejar_impl.go handles JSON serialization of http.Cookie slices to disk.
• pkg/http/client.go calls Save() after each HTTP request to ensure cookies remain persistent across tool invocations.
• The cookies file uses standard JSON encoding, making it human-readable and manually editable if necessary.

Frequently Asked Questions

What format does IPATool use to store cookies?

IPATool stores cookies as a JSON-encoded array of http.Cookie objects in the cookies.json file. This standard JSON structure contains fields like Name, Value, Path, Domain, and expiration timestamps, making it readable and portable.

Can I move my IPATool cookies to another machine?

Yes, you can copy the cookies.json file from one device's cache directory to another's matching location. Ensure the destination directory exists and IPATool has appropriate filesystem permissions to read the file on startup.

Does IPATool encrypt the stored cookies?

According to the source code analysis, IPATool does not implement additional encryption for the cookies.json file. The cookies are stored as plain JSON text, relying on standard filesystem permissions for security.

How do I force IPATool to re-authenticate?

Delete the cookies.json file from your platform's cache directory. On the next run, IPATool will fail to load existing session data and prompt for fresh authentication credentials.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}