diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..9e19ea6 --- /dev/null +++ b/.gitignore @@ -0,0 +1,7 @@ +node_modules/ +dist/ +.astro/ +.blume/ +.blume-content/ +frontend/src/generated/ +frontend/public/media/ diff --git a/README.md b/README.md index a3d3e61..a1375b7 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,14 @@ # WP Docs -This repository is an active experiment for generating WordPress core and canonical plugin documentation with `docs-agent`. +This repository publishes WordPress.com developer documentation and WordPress.org documentation from a Git-managed Markdown corpus. The goal is to produce comprehensive, massively useful WordPress documentation that is accurate, source-verified, and pleasant to navigate. The output should meet the quality bar set by the best modern documentation sites while fitting the WordPress.org documentation ecosystem. -## Current Direction +## Publishing Model -This repo is being reset around the generation workflow, content policy, provenance model, and future publishing surface. Earlier generated material has been preserved for reference, but `main` is now the working surface for the next iteration. +Markdown in Git is canonical. Markdown Database Integration (MDI) primary mode gives WordPress Studio and wp-admin a local editing interface for that same corpus; Studio Code is an optional client, not a dependency. + +Blume reads `content/runtime/` directly and owns the generated Astro presentation, local search, and static SEO output. Spacefast receives only the checked `dist/` artifact through `sf deploy dist --prebuilt`. Hosted WordPress and Push MD are migration inputs, not steady-state build or publishing dependencies. ## Repository Layout @@ -15,7 +17,10 @@ This repo is being reset around the generation workflow, content policy, provena - `content/` — generated and reviewed documentation outputs plus page-level metadata. - `recipes/` — project-specific WP Codebox recipes for reproducible generation and review runs. - `provenance/` — lightweight provenance conventions that belong with this corpus. -- `theme/wp-docs/` — prototype WordPress block theme for the docs experience. +- `content/runtime/` — canonical MDI Markdown corpus: 89 WordPress.com documents and 314 WordPress.org HelpHub articles. +- `blume.config.ts` — Blume presentation, navigation, SEO, AI, and static deployment configuration. +- `studio/` — local MDI/Studio authoring contract. +- `scripts/` — build adapters and approval-gated publishing command. - `docs/` — project architecture, decisions, and operating notes. The full-coverage generation plan is tracked in `docs/full-coverage-generation-plan.md`. @@ -44,4 +49,11 @@ That archive is useful as seed material and historical context, but it is not th - `docs-agent` owns reusable agent behavior, prompts, and bundle mechanics. - `wp-codebox` owns isolated WordPress execution, recipes, previews, and artifact bundles. -- This repo owns WordPress core and canonical plugin docs inputs, generated content, project-specific recipes, and publishing direction. +- This repo owns WordPress core and canonical plugin docs inputs, generated content, project-specific recipes, the Studio-to-static build, and publishing direction. + +## Verify A Fresh Checkout + +1. Install Node.js 22.12 or newer and run `bash tests/verify-studio-spacefast.sh`. +2. Inspect `dist/documentation/developer-tools/wp-cli/common-commands/index.html` and `dist/helphub_article/search-block/index.html` for representative nested and HelpHub routes. +3. Blume builds from Git Markdown without a running Studio site. Use Studio's MDI primary mode to edit the corpus locally, then commit those Markdown changes and rerun the build. +4. Before any human-approved publication, run `npm run publish:spacefast -- --dry-run`, which invokes `sf deploy dist --prebuilt --dry-run`. An approved publication invokes `sf deploy dist --prebuilt`; the wrapper only considers `dist/` and makes no mutation without `WP_DOCS_ALLOW_PUBLISH=1`. diff --git a/blume.config.ts b/blume.config.ts new file mode 100644 index 0000000..94d1d4c --- /dev/null +++ b/blume.config.ts @@ -0,0 +1,32 @@ +import { defineConfig } from 'blume'; + +export default defineConfig({ + title: 'WP Docs', + description: 'WordPress.com developer documentation and WordPress.org documentation.', + content: { + root: '.blume-content' + }, + github: { + owner: 'chubes4', + repo: 'wp-docs', + branch: 'feat/studio-spacefast-headless' + }, + navigation: { + tabs: [ + { label: 'WordPress.com developer documentation', path: '/documentation' }, + { label: 'WordPress.org documentation', path: '/helphub_article' } + ], + sidebar: { display: 'page' } + }, + search: { provider: 'orama' }, + ai: { llmsTxt: true }, + seo: { + sitemap: true, + robots: true, + structuredData: true + }, + deployment: { + output: 'static', + site: 'https://wp-docs.view.fast/' + } +}); diff --git a/content/_meta/navigation-search.md b/content/_meta/navigation-search.md index 108ae6a..90aa149 100644 --- a/content/_meta/navigation-search.md +++ b/content/_meta/navigation-search.md @@ -1,6 +1,6 @@ # Navigation and Search Metadata -The theme can render docs navigation from published WordPress page hierarchy. When that content is not available yet, it falls back to the committed pilot fixture at `theme/wp-docs/assets/docs-index.json`. +The static frontend renders navigation from published WordPress Page hierarchy. The deterministic build fixture is `frontend/fixtures/pages.json`; it is for CI and review only, not an authoring fallback. Search/navigation entries use this shape: diff --git a/content/runtime/README.md b/content/runtime/README.md new file mode 100644 index 0000000..bba17ec --- /dev/null +++ b/content/runtime/README.md @@ -0,0 +1,13 @@ +# WP Docs Runtime Corpus + +This directory is the Markdown Database Integration export from the `wp-docs-runtime` WordPress site. + +- Source project: `wp-docs-runtime` +- Exported: 2026-07-15 +- MDI mode: `primary` +- `documentation/`: 89 published WordPress.com documentation records +- `helphub_article/`: 314 published WordPress.org HelpHub records + +The files preserve MDI frontmatter, WordPress identity and hierarchy, source URLs, taxonomy metadata, and Markdown bodies. Git Markdown is canonical: MDI primary mode makes the same files available to local Studio/wp-admin editing, while Blume reads them for presentation. The hosted runtime was used to migrate this snapshot and is not required to build or publish it. + +Two `wp_guideline` records are not part of the publishable documentation corpus. MDI rejected them because their declared block format did not match their raw content, so they were not coerced into this snapshot. diff --git a/content/runtime/documentation/agent-skills.md b/content/runtime/documentation/agent-skills.md new file mode 100644 index 0000000..c41627f --- /dev/null +++ b/content/runtime/documentation/agent-skills.md @@ -0,0 +1,115 @@ +--- +type: document +title: Agent Skills +description: "" +resource: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/agent-skills/" +tags: +timestamp: "2026-06-16T19:29:18+00:00" +wordpress: + id: 2431 + status: publish + type: documentation + author: 0 + date: "2026-06-16 19:29:18" + date_gmt: "2026-06-16 19:29:18" + modified: "2026-06-16 19:29:18" + modified_gmt: "2026-06-16 19:29:18" + slug: agent-skills + parent: 0 + menu_order: 0 + comment_status: closed + ping_status: closed + guid: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/agent-skills/" + comment_count: 0 +--- + +Agent Skills are a curated set of reusable “skills” (prompt/tooling packages) you can add to an AI coding agent’s toolbox to help it work more effectively on WordPress-related development tasks. + +They standardize *how* an AI agent is instructed to perform common WordPress workflows, so you don’t have to re-explain context every time (e.g., how to approach UI design, static analysis, caching, and database optimization, etc.). + +They aim to make agents: + +- Safer, because they bake in best practices and guardrails +- More consistent and accounts for repeatable workflows +- Faster to onboard, as agents get immediate context + +## How they’re installed + +Agent Skills are pulled into your agent’s environment in one of two ways: + +1. **Project-local install**: Skills live inside your project directory, so everyone on the project can use the same behaviors. +2. **Global install**: Skills live in the user’s coding agent configuration directory, so they apply across all projects. + +In both cases, the coding agent reads the skills from disk and incorporates them into its operating instructions. + +Because skills are content files, the safest update model is: + +- Treat skills as versioned assets +- Periodically pull updates +- Review diffs before rolling them out broadly (especially for team-wide/shared setups) + +If you’re using [WordPress Studio](https://developer.wordpress.com/docs/developer-tools/studio), check out our [Agent Skills in WordPress Studio doc](https://developer.wordpress.com/docs/developer-tools/studio/agent-skills-wordpress-studio/) to learn how to install skills globally or per site. + +## What WordPress Agent Skills are available? + +The list of available Agent Skills may change, so be sure to visit the[ public repo ](https://github.com/WordPress/agent-skills/)for the most up-to-date information. + +There are skills for many WordPress fundamentals, including: + +- Block development +- Plugin development +- REST API +- WordPress Playground +- Performance +- Interactivity API +- Design + +## Installation options + +There are a few ways to integrate `agent-skills`, depending on your environment and how you prefer to manage dependencies. + +### Option 1: skills.sh + +If you want a quick install without cloning and building the repo manually, use [skills.sh](https://skills.sh/), an installation helper that makes it easy to add agent skill files into your local environment. + +Prerequisite: [Node.js](https://nodejs.org/en) (so you can run npx commands) + +1. [Choose the skills](https://github.com/WordPress/agent-skills#available-skills) you want to install. You can also run `npx skills add https://github.com/WordPress/agent-skills --list` to view the names of all available skills. +2. Install skills. For example, the following would install `wordpress-router`, `wp-project-triage`, `wp-block-development`, `wp-block-themes`, and `wp-plugin-development` for Claude Code: + +``` +npx skills add https://github.com/WordPress/agent-skills + --agent claude-code + --skill wordpress-router + --skill wp-project-triage + --skill wp-block-development + --skill wp-block-themes + --skill wp-plugin-development +``` + +To target a different agent, swap `--agent claude-code` for your agent (for example, `--agent cursor`). You can also install to multiple agents by passing multiple `--agent` arguments. + +During installation, you’ll be asked whether to install the skills globally or per project. Install skills globally by default by using the `--global` argument + +To remove a skill, run `npx skills remove wp-block-themes`, swapping `wp-block-themes` for the skill you wish to remove. + +To check for updates, run `npx skills check` and then `npx skills update` to update. + +When removing skills or running updates, use the same scope as when you installed them. Global installs (`--global`) affects your machine-wide skills, while project installs affect the skills checked stored alongside that codebase. + +### Option 2: + +If you need full control, or you’re contributing to the skills themselves, [clone the skills repo](https://github.com/WordPress/agent-skills) and follow [the manual build/install steps](https://github.com/WordPress/agent-skills?tab=readme-ov-file#quick-start). + +## Choosing skills: “all” vs “relevant” skills + +You may not need all of the available Agent Skills for your project. Instead, you can add skills based on what you’re working on. For example: + +- **Blocks / Gutenberg development**: `wp-block-developmen`t and `wp-interactivity-api` +- **Block themes/site editing**: `wp-block-themes` and `wpds` +- **Plugin development**: `wp-plugin-development` and `wp-abilities-api` + +Install all skills when you’re: + +- Doing broad refactors across multiple areas (blocks + themes + plugins), or +- Building platform tooling where you want maximum coverage. diff --git a/content/runtime/documentation/api/developer-console.md b/content/runtime/documentation/api/developer-console.md new file mode 100644 index 0000000..7bead2b --- /dev/null +++ b/content/runtime/documentation/api/developer-console.md @@ -0,0 +1,26 @@ +--- +type: document +title: Developer console +description: "" +resource: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/developer-console/" +tags: +timestamp: "2026-06-16T19:29:27+00:00" +wordpress: + id: 2498 + status: publish + type: documentation + author: 0 + date: "2026-06-16 19:29:27" + date_gmt: "2026-06-16 19:29:27" + modified: "2026-06-16 19:29:30" + modified_gmt: "2026-06-16 19:29:30" + slug: developer-console + parent: 2499 + menu_order: 0 + comment_status: closed + ping_status: closed + guid: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/developer-console/" + comment_count: 0 +--- + + diff --git a/content/runtime/documentation/api/getting-started.md b/content/runtime/documentation/api/getting-started.md new file mode 100644 index 0000000..57efdd3 --- /dev/null +++ b/content/runtime/documentation/api/getting-started.md @@ -0,0 +1,212 @@ +--- +type: document +title: Getting started with the REST API +description: "" +resource: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/getting-started/" +tags: +timestamp: "2026-06-16T19:29:27+00:00" +wordpress: + id: 2497 + status: publish + type: documentation + author: 0 + date: "2026-06-16 19:29:27" + date_gmt: "2026-06-16 19:29:27" + modified: "2026-06-16 19:29:30" + modified_gmt: "2026-06-16 19:29:30" + slug: getting-started + parent: 2499 + menu_order: 0 + comment_status: closed + ping_status: closed + guid: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/getting-started/" + comment_count: 0 +--- + +WordPress.com REST API allows you to view, create or edit content on any WordPress.com site, as well as any self-hosted (WordPress.org) site connected via [Jetpack](https://jetpack.me/). This includes not only blog posts and pages but also comments, tags, categories, media, site stats, notifications, sharing settings, user profiles, and many other WordPress.com features. + +Some requests (e.g. listing public posts) do not need to be authenticated, but any action that would require a user to be logged in (such as creating a post) requires an authentication token. + +To make authenticated requests, you’ll first need to [set up an account on WordPress.com](https://wordpress.com/start) if you don’t have one already. + + Looking for code examples? Check out the [WordPress.com REST API Examples repository](https://github.com/Automattic/wpcom-rest-api-examples), which contains sample projects demonstrating OAuth authentication and API usage in various programming languages and frameworks. The repository includes examples of both OAuth-based authentication for user-authorized operations and Application Password authentication for direct API endpoint access. + +## How To Use It + +There are two ways to explore the endpoints available for WordPress.com REST API: + +- The [REST API Reference docs page](https://developer.wordpress.com/docs/api/rest-api-reference/) lists available endpoints and details the input and output of each one, along with example code in curl and PHP. +- The [REST API development console](https://developer.wordpress.com/docs/api/console/) allows you to construct and try out real API requests. + +Making unauthenticated requests is simple. Since there are no special headers required, you can even open this one in your browser to see what it will return: [https://public-api.wordpress.com/rest/v1.1/sites/en.blog.wordpress.com/posts/?number=2&pretty=true](https://public-api.wordpress.com/rest/v1.1/sites/en.blog.wordpress.com/posts/?number=2&pretty=true) + +Making authenticated requests requires a few more steps. **All authenticated requests to the WordPress.com REST API require an OAuth2 access token.** This token must be obtained from WordPress.com’s OAuth2 endpoints and can be acquired through different flows, with the most relevant being: + +1. [Full OAuth2 Flow](#Full-OAuth2-Flow) – Users authorize your application through WordPress.com’s interface, granting specific permissions. This is the most secure approach and required for third-party applications. +2. [](#Credentials-Direct-Token-Exchange)[Credentials Direct Token Exchange](#Credentials-Direct-Token-Exchange) – Use an Application Password with `grant_type=password` to directly obtain a token for your own sites. This bypasses the user authorization step but requires your WordPress.com credentials. + +Both methods result in the same type of OAuth2 access token that you include in requests as `Authorization: Bearer YOUR_ACCESS_TOKEN`. The token-based approach ensures consistent security and enables per-application access control. + +We recommend OAuth2 authentication as the most secure and granular way to access the WordPress.com REST API. If you’re already familiar with OAuth2, you can skip directly to the [technical documentation](https://developer.wordpress.com/docs/api/oauth2/). + +OAuth2 lets your application act on behalf of a user without ever seeing their password. Here’s how it works: When someone wants to use your app with their WordPress.com account, your app sends them to WordPress.com to log in. WordPress.com shows them exactly what your app wants to do (like read their posts or create new ones) and asks if that’s okay. If they say yes, WordPress.com gives your app a special access token. This token is like a temporary key that lets your app do only the things the user agreed to. + +You can think of it as a three-way conversation: + +- **User:** “I’d like to make a post via this API client.” +- ***Client (App):*** “Okay. Hey, WordPress.com, I’d like to do something on behalf of this user. Can you ask them if it’s okay?” +- **WordPress.com:** “Sure. Hey, user, is it okay if Client acts on your behalf?” +- **User:** “Yes, that is okay. I trust this client to take actions for me in the future.” +- **WordPress.com:** “Okay, Client, here is a token that will allow you to take actions for this user. Keep it secret. Keep it safe.” + +Once the Client (App) has obtained the token, it can make authenticated requests to WordPress.com. Here’s how a typical interaction works: + +- ***Client (App):*** “Hello WordPress.com, I’d like to create a new post. Here’s my access token proving I’m authorized to act on behalf of the user, along with the post title, content, and other details.” +- **WordPress.com:** “I’ve validated your token and confirmed you have permission to create posts. The post has been successfully created and published. Here’s the response with the new post ID, URL, and other metadata.” + +This OAuth2 token-based authentication workflow provides secure, granular access control – the Client can only perform actions that the user explicitly authorized during the OAuth flow. The token can be revoked at any time if needed, and WordPress.com validates the token’s permissions on every request. + +The beauty of this system is that users stay in control. They can see exactly what your app is asking for, and they can revoke access anytime. Your app never stores passwords, and if a token gets compromised, it only affects that one app’s access—not the user’s entire account. + +You’ve probably seen this before when logging into websites using your Google or Facebook account. The process works the same way: you click “Log in with Facebook,” get sent to Facebook to confirm, and then get redirected back to the original site. + +From your app’s perspective, the process involves a few steps: + +- First, you register your application on WordPress.com to get a client ID. +- Then you direct users to WordPress.com with a special link that includes your client ID and tells WordPress.com where to send the user back to. +- When users authorize your app, WordPress.com redirects them back to your app with an authorization code. You exchange this code for an access token using your client secret, and then you can use that token to make API requests on behalf of the user. + +Once you have an access token, making authenticated requests is straightforward. You include the token in the Authorization header of your requests like this: `Authorization: Bearer your_token_here`. + +For complete implementation details, code examples, and security best practices, check out the [OAuth2 authentication guide](https://developer.wordpress.com/docs/api/oauth2/). + +## Base URL Structure + +The WordPress.com REST API provides a standardized base URL structure that ensures consistent access across all site types, hosting configurations, and API namespaces. All available endpoints are organized and grouped under different namespaces (such as `wp`, `rest`, and `wpcom`) and their respective versions (like `v1`, `v1.4`, `v2`, `v4`), providing logical separation between different API functionalities and allowing for independent versioning strategies. This unified approach simplifies API integration and eliminates the need to determine different URL formats based on site characteristics or API versions. + +For detailed information about available namespaces, their versions, and what endpoints each namespace provides, see the [Namespaces & Versions](https://developer.wordpress.com/docs/api/namespaces-versions/) documentation. + +### General URL Structure + +All WordPress.com REST API endpoints follow this standardized pattern: + +``` +https://public-api.wordpress.com/{namespace}/{version}/{endpoint} +``` + +<textarea aria-hidden="true" class="a8c-docs-syntax__copy-textarea">https://public-api.wordpress.com/{namespace}/{version}/{endpoint}</textarea>CopyCopied + +**Placeholders:** + +- `{namespace}`: The API namespace (e.g., ‘rest’, ‘wp’, ‘wpcom’) +- `{version}`: The API version (e.g., ‘v1’, ‘v1.4’, ‘v2’, ‘v4’) +- `{endpoint}`: The specific API endpoint you want to access + +**Examples:** + +``` +https://public-api.wordpress.com/rest/v1.4/me +https://public-api.wordpress.com/wpcom/v4/notifications +https://public-api.wordpress.com/wp/v2/posts +``` + +<textarea aria-hidden="true" class="a8c-docs-syntax__copy-textarea">https://public-api.wordpress.com/rest/v1.4/me https://public-api.wordpress.com/wpcom/v4/notifications https://public-api.wordpress.com/wp/v2/posts</textarea>CopyCopied + +### Site-Specific URL Structure + +When accessing endpoints that operate on specific WordPress.com sites, the URL structure includes a site identifier: + +``` +https://public-api.wordpress.com/{namespace}/{version}/sites/{site_id}/{endpoint} +``` + +<textarea aria-hidden="true" class="a8c-docs-syntax__copy-textarea">https://public-api.wordpress.com/{namespace}/{version}/sites/{site_id}/{endpoint}</textarea>CopyCopied + +**Parameters:** + +- `{namespace}`: The API namespace (e.g., ‘rest’, ‘wp’, ‘wpcom’) +- `{version}`: The API version (e.g., ‘v1’, ‘v1.4’, ‘v2’, ‘v4’) +- `{site_id}`: Your WordPress.com site’s unique numeric identifier +- `{endpoint}`: The specific site-related endpoint (e.g., ‘posts’, ‘pages’, ‘media’, ‘users’) + +**Examples:** + +``` +https://public-api.wordpress.com/wp/v2/sites/241031857/posts +https://public-api.wordpress.com/rest/v1.4/sites/241031857/stats +https://public-api.wordpress.com/wpcom/v2/sites/241031857/follows +``` + +<textarea aria-hidden="true" class="a8c-docs-syntax__copy-textarea">https://public-api.wordpress.com/wp/v2/sites/241031857/posts https://public-api.wordpress.com/rest/v1.4/sites/241031857/stats https://public-api.wordpress.com/wpcom/v2/sites/241031857/follows</textarea>CopyCopied + +#### Getting Your Site ID + +To use site-specific endpoints, you’ll need to obtain your site’s unique numeric identifier. You can get this info by doing a request to `/rest/v1.1/me/sites` endpoint from the API Console: + +1. Visit the [WordPress.com API Console](https://developer.wordpress.com/docs/api/console/) +2. Navigate to the `/rest/v1.1/me/sites` endpoint (that can be found at `WP.COM API - v1.1/me/sites` [in the Console](https://developer.wordpress.com/docs/api/namespaces-versions-versions/#Understanding-API-Console-Organization)) +3. Execute the request to retrieve all sites associated with your account +4. Locate the `ID` field in the response for your desired site + +The `/rest/v1.1/me/sites` endpoint returns comprehensive details about all sites associated with your WordPress.com account, including: + +- `ID`: The unique numeric site identifier (what you need for API calls) +- `name`: The site’s display name +- `URL`: The site’s public URL +- `jetpack`: Whether the site is a Jetpack-connected site +- `is_private`: Whether the site is private +- `capabilities`: What actions you can perform on the site + +**Example Response:** + +``` +{ + "sites": [ + { + "ID": 241031857, + "name": "My Blog", + "URL": "https://myblog.wordpress.com", + "jetpack": false, + "is_private": false, + "capabilities": { + "edit_posts": true, + "publish_posts": true + } + } + ] +} +``` + +<textarea aria-hidden="true" class="a8c-docs-syntax__copy-textarea">{ "sites": [ { "ID": 241031857, "name": "My Blog", "URL": "https://myblog.wordpress.com", "jetpack": false, "is_private": false, "capabilities": { "edit_posts": true, "publish_posts": true } } ] }</textarea>CopyCopied + +### Alternative URL Formats + +You may encounter some alternative URL formats: + +- **Direct site access**, like `https://yoursite.com/wp-json/wp/v2/posts` – This format works only for self-hosted sites with Jetpack. May fail due to security settings, firewall rules, or authentication issues. +- **Domain-based WordPress.com access**, like `https://public-api.wordpress.com/wp/v2/sites/yoursite.com/posts` – This format is unreliable for sites with custom domains, DNS configurations, or when domains change. + +To avoid any issues the recommended approach is to use the format with numeric site IDs which is more reliable, faster, it works consistently across all site types, and supports full WordPress.com features and authentication methods. + +## Authentication Requirements + +The WordPress.com REST API supports both authenticated and unauthenticated requests, depending on the endpoint and the data you’re trying to access. Understanding when and how to authenticate is crucial for successful API integration. + +**Unauthenticated requests** work for: + +- Public site information (e.g., site details, public posts) +- Reading public content from WordPress.com sites +- Accessing publicly available stats and data + +*Examples of unauthenticated requests:* + +``` +# Get public information about a site +curl https://public-api.wordpress.com/rest/v1.1/sites/en.blog.wordpress.com/ +Get public posts from a site +curl https://public-api.wordpress.com/wp/v2/sites/en.blog.wordpress.com/posts?per_page=5 +``` + +<textarea aria-hidden="true" class="a8c-docs-syntax__copy-textarea"># Get public information about a site curl # Get public posts from a site + +curl [https://public-api.wordpress.com/wp/v2/sites/en.blog.wordpress.com/posts?per\_page=5](https://public-api.wordpress.com/wp/v2/sites/en.blog.wordpress.com/posts?per_page=5)</textarea>CopyCopied diff --git a/content/runtime/documentation/api/guidelines-for-responsible-use-of-automattics-apis.md b/content/runtime/documentation/api/guidelines-for-responsible-use-of-automattics-apis.md new file mode 100644 index 0000000..3d01cfb --- /dev/null +++ b/content/runtime/documentation/api/guidelines-for-responsible-use-of-automattics-apis.md @@ -0,0 +1,90 @@ +--- +type: document +title: Guidelines for responsible use of Automattic’s APIs +description: "" +resource: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/guidelines-for-responsible-use-of-automattics-apis/" +tags: +timestamp: "2026-06-16T19:29:21+00:00" +wordpress: + id: 2448 + status: publish + type: documentation + author: 0 + date: "2026-06-16 19:29:21" + date_gmt: "2026-06-16 19:29:21" + modified: "2026-06-16 19:29:29" + modified_gmt: "2026-06-16 19:29:29" + slug: guidelines-for-responsible-use-of-automattics-apis + parent: 2499 + menu_order: 0 + comment_status: closed + ping_status: closed + guid: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/guidelines-for-responsible-use-of-automattics-apis/" + comment_count: 0 +--- + +We want to help you build great apps by providing efficient access to and use of WordPress.com data through our APIs. We also want to ensure that everyone in our developer community honors the high standards of integrity, performance, and privacy that our users expect from Automattic. + +When using our APIs, please keep the following guidelines in mind: + +- **We value user privacy, and so should you**. Your app should include a privacy policy that discloses, in clear terms, the information you collect from users, and how you use and store that data. +- **Refresh user data frequently**. Your app may cache or store WordPress.com content or data—but please refresh any data that you store at reasonable intervals. +- **Please don’t abuse the API**. Use of our API is free. We only ask that you not abuse it by making excessive calls through your apps. It goes without saying that we also don’t permit using our APIs to enable spam, phishing, or other types of fraud or malware. + +You also agree to abide by the API Terms of Use below. Thanks! + +One more thing—APIs like ours enable the kind of collaboration that makes the web great. We don’t think APIs [are copyrightable subject matter](https://www.eff.org/deeplinks/2014/05/dangerous-ruling-oracle-v-google-federal-circuit-reverses-sensible-lower-court), and have updated our terms to clarify that we don’t claim copyright in our APIs. + +## [Automattic’s API Terms of Use](https://developer.wordpress.com/docs/api/guidelines-for-responsible-use-of-automattics-apis/#0-automattic-s-api-terms-of-use) + +Automattic’s application programming interfaces (the “Automattic APIs”) allow you to connect to Automattic systems and to create, retrieve and use content generated by Automattic users (“Content”) from within your application and/or website (“App”). Your use of the Automattic APIs to access Automattic’s systems, including but not limited to the WordPress.com REST API, the Akismet API, the WPScan API, and the Gravatar API, is subject to these Terms of Use. + +### [1. CC0](https://developer.wordpress.com/docs/api/guidelines-for-responsible-use-of-automattics-apis/#1-1-cc0) + +To the extent possible under law, Automattic, Inc. has waived all copyright and related or neighboring rights to the declarative code that is necessary for function calls to the Automattic APIs as well as the structure, sequence and organization of the Automattic APIs. For clarity, this CC0 disclaimer does not apply to any software or code that has not been released or made public in source code form by Automattic via the API docs. For more specific information, please see . + +### [2. Restrictions and Requirements](https://developer.wordpress.com/docs/api/guidelines-for-responsible-use-of-automattics-apis/#2-2-restrictions-and-requirements) + +By using the Automattic APIs to interact with the Automattic systems, you agree to: + +- Provide true and accurate information about yourself and your App when requested by Automattic. +- Inform users about how your App copies, caches, stores or retains any Content or data, and refresh any stored or cached Content or data at a reasonable interval. +- Publish content to WordPress.com using the Automattic APIs only in accordance with the WordPress.com Terms of Service. +- Include a privacy policy which is readily accessible from all pages of your App and which complies with all applicable laws, including but not limited to the California Online Privacy Protection Act of 2003. + +And agree not to: + +- Place excessive API calls to Automattic’s systems or otherwise overburden Automattic systems, as determined by Automattic in its sole discretion. +- Share or misuse your API token. +- Use any information provided by Automattic users (including Content) to market any products or services that are competitive with Automattic, or allow third parties to do so. This obligation survives any expiration or termination of these terms of use. +- Use or allow the use of Automattic APIs or any App to send or facilitate the sending of unsolicited communications or for any fraudulent purpose, including phishing. +- Modify, decompile, reverse engineer or otherwise alter or seek to derive the trade secrets and other inherent intellectual property of the Automattic APIs. +- Use the Automattic APIs (i) to create or enable any App, website, tool, or other mechanism that is, or enables, or operates in conjunction with, any malware, spyware, adware, other malicious programs or code, or (ii) in any manner that would violate any applicable law or governmental regulation. +- Display, cache or store user passwords. +- Display, distribute, or otherwise make available content or data to governmental entities for intelligence gathering or surveillance purposes. + +### [3. Publicity](https://developer.wordpress.com/docs/api/guidelines-for-responsible-use-of-automattics-apis/#3-3-publicity) + +You may publicize that your application uses Automattic APIs, but you may not (i) issue any press release, or (ii) otherwise use the “Automattic” or “WordPress” name, any of the Automattic or WordPress logos, or any trademark, service mark, trade name, or trade dress of Automattic or any of its brands in any manner related to your use of Automattic APIs without the express written consent and approval of Automattic. + +### [4. Termination, Suspension, and Modification](https://developer.wordpress.com/docs/api/guidelines-for-responsible-use-of-automattics-apis/#4-4-termination-suspension-and-modification) + +As a condition to the access to Automattic’s systems that are granted to you, you acknowledge and agree that Automattic reserves the right to change all or any part of these Terms of Use, to suspend, limit or disable access to Automattic systems, data or content accessible through Automattic APIs, and/or to terminate these Terms of Use, in each case at any time with or without cause and without liability to you. + +Your rights to use Automattic APIs to access the Automattic systems will automatically terminate upon (i) your violation of any provision of these Terms of Use; (ii) Automattic’s notice of termination; or (iii) Automattic’s election to disable your use of Automattic APIs via the Automattic systems. Automattic may modify these terms at its discretion. Any notice of changed terms or of termination will be provided by any means including, without limitation, posting on WordPress.com, or other Automattic service, by electronic mail, or by any other communication. If you disagree with any modifications to these Terms and Conditions, your sole recourse is to stop using Automattic APIs to access the Automattic systems and your continued use of Automattic APIs to access the Automattic systems following notice of such modifications constitutes your agreement to such modifications. The provisions of Sections 3 through 8 will survive expiration or termination of these Terms of Use along with terms which, by their nature, are to survive expiration or termination of this Agreement. + +### [5. Disclaimer of Warranties](https://developer.wordpress.com/docs/api/guidelines-for-responsible-use-of-automattics-apis/#5-5-disclaimer-of-warranties) + +Automattic makes no warranties of any kind with respect to the Automattic APIs. + +### [6. Limitation of Liability](https://developer.wordpress.com/docs/api/guidelines-for-responsible-use-of-automattics-apis/#6-6-limitation-of-liability) + +Automattic will not have any liability to you arising out of these Terms and Conditions or the Automattic APIs for any indirect, incidental, consequential, special, exemplary, or punitive damages under any theory of liability arising out of or relating in any way to Automattic APIs. As a condition to receiving free access to the Automattic APIs to access the Automattic systems, you expressly agree and understand that Automattic’s aggregate liability under this agreement is limited to $5.00. + +### [7. Indemnification](https://developer.wordpress.com/docs/api/guidelines-for-responsible-use-of-automattics-apis/#7-7-indemnification) + +You will indemnify, defend, and hold Automattic, its subsidiaries, affiliates, officers, and employees, harmless from any and all claims, damages, losses, liabilities, actions, judgments, costs, and expenses (including reasonable attorneys’ fees) brought by a third party arising out of or in connection with: (i) any act or omission by you, in connection with your use of the Automattic APIs, (ii) your breach or alleged breach of any of these terms; or (iii) your App(s). Automattic may, at its option, elect to take over control of the defense and settlement of a claim subject to indemnification. You agree not to settle any such claim without the prior written consent of Automattic. + +### [8. Miscellaneous](https://developer.wordpress.com/docs/api/guidelines-for-responsible-use-of-automattics-apis/#8-8-miscellaneous) + +These Terms of Use are governed by and construed in accordance with the laws of the State of California, United States of America, without regards to its principles of conflicts of law. These Terms of Use are not assignable, transferable or sublicenseable by you (even by operation of law) except with the prior written consent of Automattic. diff --git a/content/runtime/documentation/api/index.md b/content/runtime/documentation/api/index.md new file mode 100644 index 0000000..1f9d77d --- /dev/null +++ b/content/runtime/documentation/api/index.md @@ -0,0 +1,43 @@ +--- +type: document +title: REST API +description: "" +resource: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/api/" +tags: +timestamp: "2026-06-16T19:29:27+00:00" +wordpress: + id: 2499 + status: publish + type: documentation + author: 0 + date: "2026-06-16 19:29:27" + date_gmt: "2026-06-16 19:29:27" + modified: "2026-06-16 19:29:27" + modified_gmt: "2026-06-16 19:29:27" + slug: api + parent: 0 + menu_order: 0 + comment_status: closed + ping_status: closed + guid: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/api/" + comment_count: 0 +--- + +Welcome to the WordPress.com REST API documentation. + +You can find a list of available endpoints in the [REST API Reference](https://developer.wordpress.com/docs/api/rest-api-reference/). To explore and test them interactively, head over to the [Developer Console](https://developer.wordpress.com/docs/api/console/). + +If you’re not sure how to make calls to the API check the following links to locate the topic you’re interested in. If you have never worked with the WordPress.com REST API before, consider reading through the following resources in the order listed: + +- **[Getting Started](https://developer.wordpress.com/docs/api/getting-started/)**: Check this guide to learn what the WordPress.com REST API is it and how to use it. +- **[Reference](https://developer.wordpress.com/docs/api/rest-api-reference/)**: Browse a comprehensive catalog of available REST API endpoints organized by functionality. Each endpoint includes links to detailed documentation with input parameters, output formats, and example requests in both curl and PHP. Categories include Users, Sites, Posts, Comments, Taxonomy, Media, Stats, and more. +- **[Namespaces](https://developer.wordpress.com/docs/api/namespaces-versions/)**: A guide to the three WordPress.com REST API namespaces — `/rest/`, `/wp/`, and `/wpcom/` — as shown in the [Developer Console](https://developer.wordpress.com/docs/api/console/), to help developers pick the right endpoints for their compatibility and feature needs. +- **[OAuth2 Authentication](https://developer.wordpress.com/docs/api/oauth2/)**: Learn more about how WordPress.com and Jetpack leverage OAuth2 to enable secure application access to their APIs without storing sensitive credentials, while giving users control over their connections. +- **[WordPress.com connect](https://developer.wordpress.com/docs/api/wpcc/)**: Implement the “Login with WordPress.com” functionality for user authentication. This specialized OAuth2 implementation allows millions of WordPress.com users to securely sign in to your application using their existing credentials, providing access to basic profile information while maintaining user privacy and control. +- **[Using the REST API from JS and the Browser](https://developer.wordpress.com/docs/api/rest-api-javascript/)**: Learn how to make REST API calls directly from JavaScript in web browsers. This guide covers both authenticated and unauthenticated requests using the Fetch API, explains CORS configuration requirements, and shows how to whitelist your domains to prevent cross-origin errors when building client-side applications. + +Before using the WordPress.com REST API in your applications, please review our guidelines for responsible use: + +- **[Guidelines for Responsible Use of Automattic’s APIs](https://developer.wordpress.com/docs/api/guidelines-for-responsible-use-of-automattics-apis/)**: Understand the terms of use, best practices, and ethical guidelines for using WordPress.com REST APIs. This resource covers user privacy requirements, data refresh policies, rate limiting guidelines, and the complete API Terms of Use to ensure your application meets Automattic’s standards for integrity, performance, and user protection. + +If you’re looking for the WordPress REST API that shipped as part of WordPress core in version 4.7, see [its documentation](https://developer.wordpress.org/rest-api/). Note that this API is also enabled on WordPress.com, but the URL structure on WordPress.com is slightly different than for self-hosted sites. See [this post](https://wordpress.com/blog/2016/11/11/wordpress-rest-api-on-wordpress-com/) for more details. diff --git a/content/runtime/documentation/api/namespaces-versions.md b/content/runtime/documentation/api/namespaces-versions.md new file mode 100644 index 0000000..f1cf489 --- /dev/null +++ b/content/runtime/documentation/api/namespaces-versions.md @@ -0,0 +1,207 @@ +--- +type: document +title: "Namespaces & versions" +description: "" +resource: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/namespaces-versions/" +tags: +timestamp: "2026-06-16T19:29:20+00:00" +wordpress: + id: 2444 + status: publish + type: documentation + author: 0 + date: "2026-06-16 19:29:20" + date_gmt: "2026-06-16 19:29:20" + modified: "2026-06-16 19:29:29" + modified_gmt: "2026-06-16 19:29:29" + slug: namespaces-versions + parent: 2499 + menu_order: 0 + comment_status: closed + ping_status: closed + guid: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/namespaces-versions/" + comment_count: 0 +--- + +The WordPress.com REST API is organized into three distinct namespaces, each serving specific purposes and following independent versioning schemes. Understanding these namespaces is essential for choosing the right endpoints for your integration and ensuring compatibility with both WordPress.com and self-hosted WordPress sites. + + Check the [WordPress.com API Console](https://developer.wordpress.com/docs/api/console/) to see all endpoints, [organized](#Understanding-API-Console-Organization) by namespaces and its versions + +## Overview of API Namespaces + +The WordPress.com REST API provides three main namespaces, each targeting different use cases and levels of compatibility: + +| **Namespace** | **Available Versions** | **Primary Purpose** | **WordPress Core Compatible** | +|---|---|---|---| +| `/rest/` | v1, v1.1, v1.2, v1.3, v1.4 | Legacy WordPress.com management and platform features | No | +| `/wp/` | v2 | Standard WordPress core resources following official REST API specification | Yes | +| `/wpcom/` | v2, v3, v4 | Modern WordPress.com-specific features and services | No | + +## `/rest/` Namespace – Legacy WordPress.com API + +The /rest/ namespace represents the original WordPress.com REST API, predating the WordPress core REST API. It provides comprehensive access to WordPress.com platform features and site management capabilities. + +**Available Versions:** v1, v1.1, v1.2, v1.3, v1.4 (accessed via the **WP.COM API** option in the API Console) + +**Base URLs:** + +- `https://public-api.wordpress.com/rest/v1/` +- `https://public-api.wordpress.com/rest/v1.1/` +- `https://public-api.wordpress.com/rest/v1.2/` +- `https://public-api.wordpress.com/rest/v1.3/` +- `https://public-api.wordpress.com/rest/v1.4/` + +**Key Features:** + +- Comprehensive site and user management +- WordPress.com-specific features like Stats, Reader, and Notifications +- Advanced site configuration and domain management +- Jetpack integration capabilities + +**Versioning Strategy:** Each version (v1.1–v1.4) introduced incremental improvements, new endpoints, and enhanced functionality while maintaining backward compatibility. When endpoints exist across multiple versions, newer versions typically offer additional fields, improved performance, or bug fixes. + +**Best Used For:** + +- Accessing WordPress.com-specific features not available elsewhere +- Advanced site management and configuration +- Maintaining compatibility with existing integrations +- Features like detailed stats, Reader functionality, and domain management + +**Example Endpoints:** + +- `/rest/v1.4/sites/{site}/posts` +- `/rest/v1.4/sites/{site}/stats` +- `/rest/v1.4/me/sites` +- `/rest/v1.3/read/following` + +## `/wp/` Namespace – WordPress Core REST API + +The /wp/ namespace implements the official WordPress REST API specification, ensuring full compatibility with both WordPress.com and self-hosted WordPress sites. This namespace follows the standards established by the WordPress core team. + +**Available Version:** v2 (accessed via the **WP REST API** option in the API Console) + +**Base URL:** `https://public-api.wordpress.com/wp/v2/` + +**Key Features:** + +- Standard WordPress resources (posts, pages, comments, taxonomies, users, media) +- Full compatibility with self-hosted WordPress sites +- Consistent endpoint structure following WordPress core standards +- Extensible through plugins on self-hosted sites + +**Design Philosophy:** This namespace prioritizes standardization and compatibility over WordPress.com-specific features. It mirrors the REST API available on any WordPress installation, making it ideal for applications that need to work across different WordPress environments. + +**Best Used For:** + +- New projects requiring WordPress core functionality +- Applications that must work with both WordPress.com and self-hosted sites +- Standard content management (posts, pages, media, users) +- Integrations with existing WordPress tools and plugins + +**Example Endpoints:** + +- `/wp/v2/posts` +- `/wp/v2/pages` +- `/wp/v2/users` +- `/wp/v2/media` +- `/wp/v2/sites/{site}/posts` + +## `/wpcom/` Namespace – Modern WordPress.com Platform API + +The /wpcom/ namespace represents the evolution of WordPress.com-specific API functionality, featuring modern design patterns and advanced platform features not available in WordPress core. + +**Available Versions:** v2, v3, v4 (accessed via the **WP REST API** option in the API Console) + +**Base URLs:** + +- `https://public-api.wordpress.com/wpcom/v2/` +- `https://public-api.wordpress.com/wpcom/v3/` +- `https://public-api.wordpress.com/wpcom/v4/` + +**Key Features:** + +- Modern API design with improved structure and performance +- Advanced WordPress.com services (Reader, enhanced Stats, Notifications) +- User engagement features (follows, likes, recommendations) +- Platform-specific functionality is not available in self-hosted WordPress + +**Versioning Strategy:** Each version introduces new capabilities, security improvements, and refined data structures. Unlike the `/rest/` namespace, `/wpcom/` focuses on forward-looking functionality rather than legacy compatibility. + +**Best Used For:** + +- Modern WordPress.com platform features +- User engagement and social features +- Advanced analytics and recommendations +- New integrations requiring the latest WordPress.com capabilities + +**Example Endpoints:** + +- `/wpcom/v4/me/follows` +- `/wpcom/v3/notifications` +- `/wpcom/v2/read/tags` +- `/wpcom/v4/sites/{site}/stats/insights` + +## Choosing the Right Namespace + +The choice of namespace depends on your specific requirements and compatibility needs: + +Use `/wp/v2/` when you need **Standard WordPress Functionality** like: + +- Core WordPress features (posts, pages, users, media) +- Compatibility with self-hosted WordPress sites +- Standard REST API patterns and structures +- Integration with existing WordPress tools and plugins + +Use `/wpcom/v4/` (or latest available) when you need **WordPress.com Platform Features** like: + +- Advanced WordPress.com services and social features +- Modern API design and improved performance +- Latest platform capabilities and integrations +- Features unique to the WordPress.com ecosystem + +Use `/rest/v1.4/` (or required version) when you need **Legacy Features and Compatibility** like: + +- Specific functionality is only available in legacy endpoints +- Backward compatibility with existing integrations +- Advanced site management features have not yet been migrated to newer namespaces +- Comprehensive stats and analytics capabilities + +## Version Selection Guidelines + +Within each namespace, version selection follows these principles: + +**Multiple Versions Available:** When endpoints exist across multiple versions, newer versions typically provide: + +- Additional response fields and parameters +- Improved performance and reliability +- Bug fixes and security enhancements +- Enhanced functionality while maintaining backward compatibility + +**Recommended Approach:** Always use the latest available version unless: + +- Your integration depends on specific behavior in older versions +- You’re maintaining legacy code that requires specific API responses +- Compatibility requirements dictate a particular version + +## Understanding API Console Organization + +The [WordPress.com API Console](https://developer.wordpress.com/docs/api/console/) organizes namespaces into two main categories: + +- **WP.COM API**: Contains all `/rest/` namespace versions (v1–v1.4) +- **WP REST API**: Contains `/wp/v2/` and all `/wpcom/` namespace versions (v2–v4) + +This organization reflects the evolution from WordPress.com-specific APIs to standardized WordPress core APIs and modern platform features. + +## Migration Considerations + +When planning integrations or updating existing ones: + +**New Projects:** Start with `/wp/v2/` for core functionality and `/wpcom/v4/` for platform-specific features. + +**Existing Integrations:** Consider migrating from /rest/ endpoints to newer namespaces when: + +- Equivalent functionality exists in `/wp/v2/` or `/wpcom/` +- You need improved performance or additional features +- Long-term maintenance and support are priorities + +**Feature Availability:** Some advanced features remain exclusive to the /rest/ namespace. Evaluate feature requirements before migration to ensure all necessary functionality is available in target namespaces. diff --git a/content/runtime/documentation/api/oauth2.md b/content/runtime/documentation/api/oauth2.md new file mode 100644 index 0000000..27f8c1f --- /dev/null +++ b/content/runtime/documentation/api/oauth2.md @@ -0,0 +1,501 @@ +--- +type: document +title: OAuth2 authentication +description: "" +resource: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/oauth2/" +tags: +timestamp: "2026-06-16T19:29:26+00:00" +wordpress: + id: 2487 + status: publish + type: documentation + author: 0 + date: "2026-06-16 19:29:26" + date_gmt: "2026-06-16 19:29:26" + modified: "2026-06-16 19:29:30" + modified_gmt: "2026-06-16 19:29:30" + slug: oauth2 + parent: 2499 + menu_order: 0 + comment_status: closed + ping_status: closed + guid: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/oauth2/" + comment_count: 0 +--- + +[OAuth2](https://oauth.net/2/) lets applications securely access WordPress.com and Jetpack sites without needing users’ passwords. It provides fine-grained control over what each app can access. + +OAuth2 lets apps request only the specific permissions they need through “scopes”. When users authorize an app, they can see and control exactly what access they’re granting. + +Users sign in with their WordPress.com account and can approve or deny the requested permissions, maintaining control over their data while safely connecting apps. + +Looking for code examples? Check out the [WordPress.com REST API Examples repository](https://github.com/Automattic/wpcom-rest-api-examples), which contains sample projects demonstrating OAuth authentication and API usage in various programming languages and frameworks. The repository includes examples of both OAuth-based authentication for user-authorized operations and Application Password authentication for direct API endpoint access. + +## Prerequisites + +Before developing your OAuth2 application, you need to have a WordPress.com application registered with the following data: + +1. **Client ID**: Identifies your application +2. **Client Secret**: Authenticates your application (keep secure) +3. **Redirect URI**: Where users return after authorization + +You can obtain these credentials through the [WordPress.com Applications Manager](https://developer.wordpress.com/apps/). + +Use [this form](https://developer.wordpress.com/apps/new/) to register a new WordPress.com Application + +## OAuth2 endpoints + +If you’re new to OAuth2, you can learn more at . For WordPress.com integration, you need to understand the core OAuth2 endpoints available under the `https://public-api.wordpress.com/oauth2/` namespace. These endpoints work consistently for both WordPress.com sites and Jetpack-connected sites. + +### Authorization Endpoint + +**Endpoint**: `https://public-api.wordpress.com/oauth2/authorize` + +**Method**: GET (via user redirect) + +This is where the OAuth2 flow begins. Users are presented with an authorization interface to review and approve the permissions your application is requesting. The endpoint validates your application credentials, redirect URI, and generates secure authorization codes for token exchange. + +**Required Parameters**: + +- `client_id`: Your application’s client ID +- `redirect_uri`: Must match registered redirect URI +- `response_type`: “code” for [Authorization Code Flow](#Authorization-Code-Flow) or “token” for [Implicit Flow](#Implicit-Flow) + +**Optional Parameters**: + +- `scope`: Space-separated permissions (defaults to single-blog access) +- `state`: Recommended for CSRF protection +- `blog`: Specific blog URL or ID for single-site access + +**Example Authorization URL** (Authorization Code Flow): + +`https://public-api.wordpress.com/oauth2/authorize?client_id=12345&redirect_uri=https%3A%2F%2Fyourapp.com%2Fcallback&response_type=code&scope=posts%20media&state=abc123xyz` + +**Example Authorization URL** (Implicit Flow): + +`https://public-api.wordpress.com/oauth2/authorize?client_id=12345&redirect_uri=https%3A%2F%2Fyourapp.com%2Fcallback&response_type=token&scope=posts%20media&state=abc123xyz` + +**Example Authorization URL** (Specific Blog): + +`https://public-api.wordpress.com/oauth2/authorize?client_id=12345&redirect_uri=https%3A%2F%2Fyourapp.com%2Fcallback&response_type=code&blog=yourblog.wordpress.com&scope=posts%20media&state=abc123xyz` + +**Response/Action**: After user approval, redirects to your redirect\_uri with: + +- **Authorization Code Flow**: `?code=AUTHORIZATION_CODE&state=YOUR_STATE` +- **Implicit Flow**: `#access_token=TOKEN&expires_in=64800&token_type=bearer&site_id=BLOG_ID` +- **User denial**: `?error=access_denied` + +**Important Note**: The redirect\_uri parameter must exactly match the redirect URI registered when creating your application. Even minor differences (like missing trailing slashes) will cause the authorization to fail. This is a security measure to prevent malicious redirects. + +### Token Request Endpoint + +**Endpoint**: `https://public-api.wordpress.com/oauth2/token` + +**Method**: POST + +This secure server-to-server endpoint handles two different grant types for obtaining access tokens. Choose the appropriate grant type based on your use case: + +#### Authorization Code Grant (Production Use) + +Use this grant type for all production applications. It exchanges authorization codes (received from user authorization) for access tokens while keeping your client secret secure. + +**Required Parameters**: + +- `client_id`: Your application’s client ID +- `client_secret`: Your application’s client secret +- `code`: Authorization code from the [authorization step](#Authorization-Endpoint) +- `grant_type`: Must be “authorization\_code” +- `redirect_uri`: Must match the authorization redirect URI + +**Example Request**: + +``` +curl -X POST https://public-api.wordpress.com/oauth2/token +  -d "client_id=12345" +  -d "client_secret=your_client_secret" +  -d "code=received_authorization_code" +  -d "grant_type=authorization_code" +  -d "redirect_uri=https://yourapp.com/callback" +``` + +curl -X POST https://public-api.wordpress.com/oauth2/token -d "client\_id=12345" -d "client\_secret=your\_client\_secret" -d "code=received\_authorization\_code" -d "grant\_type=authorization\_code" -d "redirect\_uri=https://yourapp.com/callback"CopyCopied + +#### Password Grant (Development & Testing Only) + +This grant type allows application owners to obtain tokens directly using their WordPress.com credentials, bypassing the [user authorization flow](#Authorization-Endpoint). + +**Use Password Grant For**: + +- Testing API endpoints during development +- Automated testing where user authorization simulation is impractical +- Personal development on your own WordPress.com sites + +**Security Restrictions**: + +- Only works with **your own** WordPress.com credentials (not other users’) +- Requires exposing credentials in your code +- Bypasses OAuth2’s user consent and security benefits +- **Never use in production applications** + +**Required Parameters**: + +- `client_id`: Your application’s client ID +- `client_secret`: Your application’s client secret +- `grant_type`: Must be “password” +- `username`: Your WordPress.com username +- `password`: Your WordPress.com password (or [Application Password](https://wordpress.com/support/security/two-step-authentication/application-specific-passwords/) if 2FA enabled) + +**Example Request**: + +``` +curl -X POST https://public-api.wordpress.com/oauth2/token +  -d "client_id=12345" +  -d "client_secret=your_client_secret" +  -d "grant_type=password" +  -d "username=your_username" +  -d "password=your_password_or_app_password" +``` + +curl -X POST https://public-api.wordpress.com/oauth2/token -d "client\_id=12345" -d "client\_secret=your\_client\_secret" -d "grant\_type=password" -d "username=your\_username" -d "password=your\_password\_or\_app\_password"CopyCopied + +**Two-Factor Authentication**: If you have 2FA enabled, create an Application Password in your [WordPress.com Account Settings](https://wordpress.com/me/security) and use that instead of your regular password. + +**Migration Path**: Start with Password Grant for development convenience, but implement Authorization Code Flow before launching to production. Think of Password Grant as a development shortcut that must be replaced with proper user authorization in live applications. + +**Token Response Format** (Both Grant Types): + +``` +{ +    "access_token": "YOUR_API_TOKEN", +    "blog_id": "blog_id_number",  +    "blog_url": "https://yourblog.wordpress.com", +    "token_type": "bearer" +} +``` + +{ "access\_token": "YOUR\_API\_TOKEN", "blog\_id": "blog\_id\_number", "blog\_url": "https://yourblog.wordpress.com", "token\_type": "bearer" }CopyCopied + +### Token Information Endpoint + +**Endpoint**: `https://public-api.wordpress.com/oauth2/token-info` + +**Method**: GET + +Provides secure token validation and inspection. Returns detailed information about tokens, including user ID, blog ID, and scope permissions. Essential for verifying token authenticity, especially when tokens are transmitted between systems or in mobile applications. + +**Required Parameters**: + +- `client_id`: Your application’s client ID +- `token`: The access token to validate + +**Example Request**: + +`GET https://public-api.wordpress.com/oauth2/token-info?client_id=12345&token=your_access_token_here` + +**Example CURL Request**: + +`curl "https://public-api.wordpress.com/oauth2/token-info?client_id=12345&token=your_access_token_here"` + +**Response Format** (Valid Token): + +``` +{ +    "client_id": "12345", +    "user_id": "123456789", +    "blog_id": "987654321",  +    "scope": "posts,media" +} +``` + +{ "client\_id": "12345", "user\_id": "123456789", "blog\_id": "987654321", "scope": "posts,media" }CopyCopied + +**Response** (Invalid Token): Returns an error if the token was not authorized for your application or is invalid. + +### Authentication Endpoint + +**Endpoint**: `https://public-api.wordpress.com/oauth2/authenticate` + +**Method**: GET (via user redirect) + +A specialized endpoint for WordPress.com Connect applications that only need basic user identity verification. Optimized for “Login with WordPress.com” functionality, designed for identity verification rather than content management. + +**Required Parameters**: + +- `client_id`: Your application’s client ID +- `redirect_uri`: Must match registered redirect URI +- `response_type`: Use “code” for secure server-side exchange + +**Optional Parameters**: + +- `scope`: Typically “auth” for basic profile access +- `state`: Recommended for CSRF protection + +**Example Authentication URL**: + +`https://public-api.wordpress.com/oauth2/authenticate?client_id=12345&redirect_uri=https%3A%2F%2Fyourapp.com%2Fauth-callback&response_type=code&scope=auth&state=random_secure_string` + +**Response/Action**: After user approval, redirects to your redirect\_uri with an authorization code. Exchange this code at the token endpoint to receive a token with limited scope, typically providing access only to: + +**Available API Access**: + +- `/me/` endpoint for basic user profile information +- User identity verification data (ID, username, email, avatar\_URL, verified status) + +## OAuth2 Workflows + +WordPress.com supports two main OAuth2 workflows, each designed for different application types and security requirements: + +### Authorization Code Flow (Recommended) + +The Authorization Code Flow is the standard OAuth2 workflow for **server-side applications** where you can securely store client secrets. This flow provides the highest security by exchanging an authorization code for an access token through a secure server-to-server request. + +**Security advantage**: The client secret never appears in client-side code, and access tokens are obtained through authenticated server requests. + +[![Flowchart illustrating the OAuth2 authorization code flow, detailing steps for user login, authorization page display, permission approval, and access token retrieval across user, application, and WordPress.com authorization server.](https://developer.wordpress.com/wp-content/uploads/2024/02/image-4.png?w=1024)](https://developer.wordpress.com/wp-content/uploads/2024/02/image-4.png)### Implicit Flow (Legacy) + +The Implicit Flow was designed for **browser-based applications** where the access token is returned directly in the URL fragment. However, this approach is now considered less secure and has been largely deprecated in favor of more secure alternatives like PKCE (Proof Key for Code Exchange). + +**Important**: We recommend using the Authorization Code Flow whenever possible for enhanced security. + +[![Flowchart illustrating the OAuth2 Implicit Flow (Legacy) process, showing steps for user authorization, including initiating login requests, displaying authorization pages, and redirecting with authorization codes.](https://developer.wordpress.com/wp-content/uploads/2024/02/image-6.png?w=1024)](https://developer.wordpress.com/wp-content/uploads/2024/02/image-6.png)## OAuth2 Scopes and Permissions + +OAuth2’s power lies in its granular permission system. When requesting authorization, you specify scopes that define exactly what your application can access. + +### Available Scopes + +- **users**: View user information +- **sites**: View general site information and options +- **posts**: View and manage posts +- **comments**: View and manage post comments +- **taxonomy**: View and manage tags and categories +- **follow**: Follow and unfollow blogs +- **sharing**: Connect social media services +- **freshly-pressed**: View Freshly Pressed posts +- **notifications**: View and manage user notifications +- **insights**: View analytics for your application +- **read**: Manage and view Reader subscriptions +- **stats**: View site statistics +- **media**: Manage site media +- **menus**: View and manage site menus +- **batch**: Batch multiple GET requests +- **videos**: View video information + +### Special Scopes + +- **global**: Grants comprehensive access to user data across all WordPress.com services and connected sites +- **auth**: Limited scope providing access only to the `/me/` endpoint for basic authentication flows. See [WordPress.com Connect](https://developer.wordpress.com/docs/api/wpcc/) for more related info. + +### Scope Best Practices + +Always follow the **principle of least privilege**: + +``` +// Request only necessary permissions +const scopes = 'posts,media'; // Not 'global' unless truly needed +``` + +// Request only necessary permissions const scopes = 'posts,media'; // Not 'global' unless truly neededCopyCopied + +## Implementing OAuth2 Authentication + +### Step 1: Authorization Request + +Direct users to the authorization endpoint with the required parameters: + +#### Required Parameters + +- **`client_id`**: Your application’s client ID +- **`redirect_uri`**: Must match the URI registered in your application settings +- **`response_type`**: Use “code” for [Authorization Code Flow](#Authorization-Code-Flow) or “token” for [Implicit Flow](#Implicit-Flow) + +#### Optional Parameters + +- **`blog`**: Specific blog URL or ID for single-site access +- **`scope`**: Space-separated list of requested permissions +- **`state`**: Recommended security parameter to prevent CSRF attacks + +#### Example Authorization URL + +``` +const authUrl = `https://public-api.wordpress.com/oauth2/authorize?` + +  `client_id=${clientId}&` + +  `redirect_uri=${encodeURIComponent(redirectUri)}&` + +  `response_type=code&` + +  `scope=posts,media&` + +  `state=${secureRandomString}`; + +// // Redirect user to authorization +window.location.href = authUrl; +``` + +const authUrl = `https://public-api.wordpress.com/oauth2/authorize?` + `client\_id=${clientId}&` + `redirect\_uri=${encodeURIComponent(redirectUri)}&` + `response\_type=code&` + `scope=posts,media&` + `state=${secureRandomString}`; // // Redirect user to authorization window.location.href = authUrl;CopyCopied + +### Step 2: Authorization Code Exchange + +After user authorization, you’ll receive (at the redirect\_url location) an authorization code that must be exchanged for an access token. + +#### Server-Side Token Exchange + +Make a POST request to the token endpoint: + +``` +$curl = curl_init( 'https://public-api.wordpress.com/oauth2/token' ); + +curl_setopt( $curl, CURLOPT_POST, true ); +curl_setopt( $curl, CURLOPT_POSTFIELDS, array( +    'client_id' => $your_client_id, +    'redirect_uri' => $your_redirect_url, +    'client_secret' => $your_client_secret_key, +    'code' => $_GET['code'], // The authorization code +    'grant_type' => 'authorization_code' +) ); + +curl_setopt( $curl, CURLOPT_RETURNTRANSFER, 1); + +$auth = curl_exec( $curl ); +$secret = json_decode( $auth ); +$access_token = $secret->access_token; +``` + +$curl = curl\_init( 'https://public-api.wordpress.com/oauth2/token' ); curl\_setopt( $curl, CURLOPT\_POST, true ); curl\_setopt( $curl, CURLOPT\_POSTFIELDS, array( 'client\_id' => $your\_client\_id, 'redirect\_uri' => $your\_redirect\_url, 'client\_secret' => $your\_client\_secret\_key, 'code' => $\_GET\['code'\], // The authorization code 'grant\_type' => 'authorization\_code' ) ); curl\_setopt( $curl, CURLOPT\_RETURNTRANSFER, 1); $auth = curl\_exec( $curl ); $secret = json\_decode( $auth ); $access\_token = $secret->access\_token;CopyCopied + +#### Successful Response + +``` +{ +    "access_token": "YOUR_API_TOKEN", +    "blog_id": "blog_id_number", +    "blog_url": "https://yourblog.wordpress.com", +    "token_type": "bearer" +} +``` + +{ "access\_token": "YOUR\_API\_TOKEN", "blog\_id": "blog\_id\_number", "blog\_url": "https://yourblog.wordpress.com", "token\_type": "bearer" }CopyCopied + +### Step 3: Making Authenticated API Calls + +Use the Bearer token in the Authorization header for all API requests: + +``` +$access_token = 'YOUR_API_TOKEN'; +$curl = curl_init( 'https://public-api.wordpress.com/rest/v1/me/' ); + +curl_setopt( $curl, CURLOPT_HTTPHEADER, array( 'Authorization: Bearer ' . $access_token ) ); +curl_setopt( $curl, CURLOPT_RETURNTRANSFER, 1 ); + +$response = curl_exec( $curl ); +``` + +$access\_token = 'YOUR\_API\_TOKEN'; $curl = curl\_init( 'https://public-api.wordpress.com/rest/v1/me/' ); curl\_setopt( $curl, CURLOPT\_HTTPHEADER, array( 'Authorization: Bearer ' . $access\_token ) ); curl\_setopt( $curl, CURLOPT\_RETURNTRANSFER, 1 ); $response = curl\_exec( $curl );CopyCopied + +## Advanced OAuth2 Features + +### Token Scope Management + +Different token scopes provide different access levels: + +- **Single-blog tokens**: Grant access to one specific blog +- **Global tokens**: Provide access to all user’s WordPress.com and connected Jetpack sites +- **User-specific endpoints**: Some endpoints (likes, follows) work across blogs with any user token + +### Client-Side (Implicit) OAuth + +For client-side applications, tokens can be returned in the URL fragment using the [Implicit Flow](#Implicit-Flow): + +`https://yourapp.com/callback#access_token=TOKEN&expires_in=64800&token_type=bearer&site_id=BLOG_ID` + +**Important considerations**: + +- Tokens currently expire after two weeks +- Use the expires\_in value to handle token refresh +- Suitable only for public clients where secrets cannot be stored securely + +### Token Validation and Management + +Managing OAuth2 tokens properly is crucial for a robust application. This includes validating tokens, handling API responses, and gracefully managing token expiration or insufficient permissions. + +[![Flowchart illustrating the process of validating an application token, including user identification, API requests, and handling various response scenarios such as token validity, expiration, and permission issues.](https://developer.wordpress.com/wp-content/uploads/2024/02/image-7.png?w=579)](https://developer.wordpress.com/wp-content/uploads/2024/02/image-7.png)#### Token Information Endpoint + +Verify token authenticity using the token info endpoint: + +`GET https://public-api.wordpress.com/oauth2/token-info?client_id=your_client_id&token=your_token` + +**Valid response**: + +``` +{ +    "client_id": "your_client_id", +    "user_id": "user_id_number", +    "blog_id": "blog_id_number", +    "scope": "posts,media" +} +``` + +{ "client\_id": "your\_client\_id", "user\_id": "user\_id\_number", "blog\_id": "blog\_id\_number", "scope": "posts,media" }CopyCopied + +## Development and Testing + +### Testing with Password Grant (Client Owners Only) + +Application owners can use the [password grant](#Password-Grant) to get the authentication token: + +``` +$curl = curl_init( 'https://public-api.wordpress.com/oauth2/token' ); + +curl_setopt( $curl, CURLOPT_POST, true ); + +curl_setopt( $curl, CURLOPT_POSTFIELDS, array( +    'client_id' => $your_client_id, +    'client_secret' => $your_client_secret_key, +    'grant_type' => 'password', +    'username' => $your_wpcom_username, +    'password' => $your_wpcom_password, // Use Application Password if 2FA enabled +) ); + +curl_setopt( $curl, CURLOPT_RETURNTRANSFER, 1); +$auth = curl_exec( $curl ); +$auth = json_decode( $auth ); +$access_token = $auth->access_token; +``` + +$curl = curl\_init( 'https://public-api.wordpress.com/oauth2/token' ); curl\_setopt( $curl, CURLOPT\_POST, true ); curl\_setopt( $curl, CURLOPT\_POSTFIELDS, array( 'client\_id' => $your\_client\_id, 'client\_secret' => $your\_client\_secret\_key, 'grant\_type' => 'password', 'username' => $your\_wpcom\_username, 'password' => $your\_wpcom\_password, // Use Application Password if 2FA enabled ) ); curl\_setopt( $curl, CURLOPT\_RETURNTRANSFER, 1); $auth = curl\_exec( $curl ); $auth = json\_decode( $auth ); $access\_token = $auth->access\_token;CopyCopied + +**Important**: This method requires an [Application Password](https://wordpress.com/support/security/two-step-authentication/application-specific-passwords/) if two-factor authentication is enabled. + +## Security Best Practices and Error Handling + +### Implementation Guidelines + +1. **State Parameter Validation**: Always validate the state parameter to prevent CSRF attacks +2. **Secure Token Storage**: Store access tokens securely using appropriate encryption +3. **Minimum Scope Requests**: Request only the permissions your application actually needs +4. **Clear User Communication**: Explain why specific permissions are required +5. **Proper Error Handling**: Handle authorization failures, token expiration, and scope changes gracefully + +### HTTPS Requirements + +All OAuth2 communications must use HTTPS to protect tokens and authorization codes during transmission. + +### Token Management + +- Store access tokens securely on the server side +- Implement appropriate token refresh mechanisms +- Provide clear documentation about token lifecycle +- Handle token expiration gracefully in your application + +### Error Handling + +Common OAuth2 errors and their meanings: + +- **access\_denied**: User declined authorization +- **invalid\_client**: Invalid client credentials +- **invalid\_grant**: Invalid or expired authorization code +- **invalid\_scope**: Requested scope is invalid or unavailable + +Always implement comprehensive error handling to provide users with clear feedback when authorization issues occur. + +## Conclusion + +OAuth2 provides a secure, user-friendly authentication method for WordPress.com integrations. By implementing proper scope management, security practices, and error handling, you can build applications that respect user privacy while providing powerful functionality. The granular permission system ensures users maintain control over their data while enabling your application to deliver valuable features. + +For complete API endpoint documentation and additional examples, visit the [WordPress.com REST API Reference](https://developer.wordpress.com/docs/api/rest-api-reference). diff --git a/content/runtime/documentation/api/rest-api-javascript.md b/content/runtime/documentation/api/rest-api-javascript.md new file mode 100644 index 0000000..16a0b4d --- /dev/null +++ b/content/runtime/documentation/api/rest-api-javascript.md @@ -0,0 +1,93 @@ +--- +type: document +title: "Using the REST API from JavaScript & the browser (CORS)" +description: "" +resource: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/rest-api-javascript/" +tags: +timestamp: "2026-06-16T19:29:26+00:00" +wordpress: + id: 2490 + status: publish + type: documentation + author: 0 + date: "2026-06-16 19:29:26" + date_gmt: "2026-06-16 19:29:26" + modified: "2026-06-16 19:29:30" + modified_gmt: "2026-06-16 19:29:30" + slug: rest-api-javascript + parent: 2499 + menu_order: 0 + comment_status: closed + ping_status: closed + guid: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/rest-api-javascript/" + comment_count: 0 +--- + +The [REST API](https://developer.wordpress.com/docs/api/) can be used directly from the browser using Javascript. If you whitelist the domains you want to use for your application, we will send the correct [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS) headers. Both authenticated and unauthenticated calls are supported. To make authenticated requests follow the [implicit section of the OAuth documentation](https://developer.wordpress.com/docs/api/oauth2/#Implicit-Flow) to get a user token. + +All examples use plain JavaScript with the Fetch API. + +## Unauthenticated Requests + +You can make unauthenticated GET requests with no additional work. Just make a simple HTTP request: + +``` +fetch("https://public-api.wordpress.com/rest/v1/sites/en.blog.wordpress.com/") + .then(response => response.json()) + .then(data => { + // data contains site information + }) + .catch(error => { + console.error('Error:', error); + }); +``` + +fetch("https://public-api.wordpress.com/rest/v1/sites/en.blog.wordpress.com/") .then(response => response.json()) .then(data => { // data contains site information }) .catch(error => { console.error('Error:', error); });CopyCopied + +## Authenticated Requests + +To make authenticated requests, you must provide a token that verifies the resource owner has granted the app permission to act on their behalf. + +### Get/Store User Token + +To get a valid access token for the current user, your app must use the OAuth workflow, where the user explicitly grants permission. For client-side apps, you can use the [OAuth 2.0 implicit flow](https://developer.wordpress.com/docs/api/oauth2/), which doesn’t require a client secret. + +### Make the request + +When making the request you just need to pass the access token as a header. + +``` +fetch(`https://public-api.wordpress.com/rest/v1/sites/${site_id}/posts/new`, { + method: 'POST', + headers: { + 'Authorization': `Bearer ${access_token}`, + 'Content-Type': 'application/json' + }, + body: JSON.stringify({ + content: 'testing test' + }) +}) +.then(response => response.json()) +.then(data => { + // Handle the response data +}) +.catch(error => { + console.error('Error:', error); +}); +``` + +fetch(`https://public-api.wordpress.com/rest/v1/sites/${site\_id}/posts/new`, { method: 'POST', headers: { 'Authorization': `Bearer ${access\_token}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ content: 'testing test' }) }) .then(response => response.json()) .then(data => { // Handle the response data }) .catch(error => { console.error('Error:', error); });CopyCopied + +### Whitelist Origins + +To prevent CORS errors when making authenticated API calls from your browser-based application, you must whitelist the domains that will be making those requests. If you don’t whitelist your domain, you’ll receive a CORS error like this: + +``` +Access to XMLHttpRequest at 'https://public-api.wordpress.com/rest/v1/me/' from origin 'https://www.my-demo-domain.com' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource. +``` + +Access to XMLHttpRequest at 'https://public-api.wordpress.com/rest/v1/me/' from origin 'https://www.my-demo-domain.com' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.CopyCopied + +You can whitelist your domain(s) while creating or configuring your application with the [application manager](https://developer.wordpress.com/apps/). + +[![Text input field for whitelisting JavaScript origins with instructions for making authenticated GET requests.](https://wpdeveloperstaging.files.wordpress.com/2024/02/4e730-screen-shot-2014-05-15-at-12-39-29-pm.png)](https://wpdeveloperstaging.files.wordpress.com/2024/02/4e730-screen-shot-2014-05-15-at-12-39-29-pm.png)To whitelist multiple domains, enter each domain URL on a separate line in the “Javascript Origins” input field. diff --git a/content/runtime/documentation/api/rest-api-reference.md b/content/runtime/documentation/api/rest-api-reference.md new file mode 100644 index 0000000..0a2f7df --- /dev/null +++ b/content/runtime/documentation/api/rest-api-reference.md @@ -0,0 +1,397 @@ +--- +type: document +title: REST API reference +description: "" +resource: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/rest-api-reference/" +tags: +timestamp: "2026-06-16T19:29:20+00:00" +wordpress: + id: 2443 + status: publish + type: documentation + author: 0 + date: "2026-06-16 19:29:20" + date_gmt: "2026-06-16 19:29:20" + modified: "2026-06-16 19:29:29" + modified_gmt: "2026-06-16 19:29:29" + slug: rest-api-reference + parent: 2499 + menu_order: 0 + comment_status: closed + ping_status: closed + guid: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/rest-api-reference/" + comment_count: 0 +--- + +Welcome to the WordPress.com REST API reference docs page. This doc page lists a selection of available endpoints, with each linking to a full page detailing the input, output, and example code in curl and PHP. + +Alternatively, the [Development Console](https://developer.wordpress.com/docs/api/console/) provides a complete view of all available endpoints grouped by [namespace and version](https://developer.wordpress.com/docs/api/namespaces-versions-versions/). While it doesn’t provide in-depth details for each endpoint, it does allow you to construct and test real API requests to each endpoint interactively. + +When making API requests, you’ll need to use the [standardized WordPress.com REST API URL format](https://developer.wordpress.com/docs/api/getting-started/#1-base-url-structure): `https://public-api.wordpress.com/{namespace}/{version}/sites/{site_id}/{endpoint}`. + +For detailed information about URL structures, obtaining your site ID, and best practices for making API requests, see the [Getting Started guide](https://developer.wordpress.com/docs/api/getting-started/). + +For more information about a particular endpoint, click on its name under the Resource header. You’ll be taken to the endpoint’s documentation page, which includes what query parameters the endpoint will accept, what the JSON object’s parameters will be in the response, and an example query/response. + +## Users + +View user information data such as username, name, email, blog, and Gravatar. + +| **Resource** | **Description** | +|---|---| +| [GET/sites/$site/users](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/users/) | List the users of a site. | +| [POST/sites/$site/users/$user\_id](https://developer.wordpress.com/docs/api/1.1/post/sites/%24site/users/%24user_id/) | Update details of a user of a site. | +| [POST/sites/$site/invites/new](https://developer.wordpress.com/docs/api/1.1/post/sites/%24site/invites/new/) | Invite one or more users to your site. | +| [GET/sites/$site/users/login:$user\_id](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/users/login:%24user_id/) | Get details of a user of a site by login. | +| [POST/sites/$site/users/$user\_ID/delete](https://developer.wordpress.com/docs/api/1.1/post/sites/%24site/users/%24user_ID/delete/) | Deletes or removes a user of a site. | +| [GET/users/suggest](https://developer.wordpress.com/docs/api/1.1/get/users/suggest/) | Get a list of possible users to suggest for @mentions. | +| [GET/me](https://developer.wordpress.com/docs/api/1.1/get/me/) | Get metadata about the current user. | +| [GET/me/billing-history](https://developer.wordpress.com/docs/api/1.1/get/me/billing-history/) | Get list of current user’s billing history and upcoming charges. | +| [GET/me/settings/](https://developer.wordpress.com/docs/api/1.1/get/me/settings/) | Get the current user’s settings. | +| [POST/me/settings/](https://developer.wordpress.com/docs/api/1.1/post/me/settings/) | Update the current user’s settings. | +| [GET/me/preferences/](https://developer.wordpress.com/docs/api/1.1/get/me/preferences/) | Get the current user’s settings. | +| [POST/me/preferences/](https://developer.wordpress.com/docs/api/1.1/post/me/preferences/) | Update the current user’s preferences. | +| [POST/me/settings/password/validate](https://developer.wordpress.com/docs/api/1.1/post/me/settings/password/validate/) | Verify strength of a user’s new password. | +| [GET/me/settings/profile-links/](https://developer.wordpress.com/docs/api/1.1/get/me/settings/profile-links/) | Get current user’s profile links. | +| [POST/me/settings/profile-links/new](https://developer.wordpress.com/docs/api/1.1/post/me/settings/profile-links/new/) | Add a link to current user’s profile. | +| [POST/me/settings/profile-links/$slug/delete](https://developer.wordpress.com/docs/api/1.1/post/me/settings/profile-links/%24slug/delete/) | Delete a link from current user’s profile. | +| [GET/me/connected-applications/](https://developer.wordpress.com/docs/api/1.1/get/me/connected-applications/) | Get current user’s connected applications. | +| [GET/me/connected-applications/$ID](https://developer.wordpress.com/docs/api/1.1/get/me/connected-applications/%24ID/) | Get one of current user’s connected applications. | +| [POST/me/connected-applications/$ID/delete](https://developer.wordpress.com/docs/api/1.1/post/me/connected-applications/%24ID/delete/) | Delete one of current user’s connected application access tokens. | +| [GET/me/two-step](https://developer.wordpress.com/docs/api/1.1/get/me/two-step/) | Get information about current user’s two factor configuration. | +| [POST/me/two-step/sms/new](https://developer.wordpress.com/docs/api/1.1/post/me/two-step/sms/new/) | Sends a two-step code via SMS to the current user. | +| [GET/me/likes/](https://developer.wordpress.com/docs/api/1.1/get/me/likes/) | Get a list of the current user’s likes. | + +## Sites + +View general site information and options. + +| **Resource** | **Description** | +|---|---| +| [GET/sites/$site/shortcodes/render](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/shortcodes/render/) | Get a rendered shortcode for a site. Note: The current user must have publishing access. | +| [GET/sites/$site/shortcodes](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/shortcodes/) | Get a list of shortcodes available on a site. Note: The current user must have publishing access. | +| [GET/sites/$site/embeds/render](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/embeds/render/) | Get a rendered embed for a site. Note: The current user must have publishing access. | +| [GET/sites/$site/embeds](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/embeds/) | Get a list of embeds available on a site. Note: The current user must have publishing access. | +| [GET/sites/$site](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/) | Get information about a site. | +| [GET/sites/$site/page-templates](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/page-templates/) | Get a list of page templates supported by a site. | +| [GET/sites/$site/post-types](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/post-types/) | Get a list of post types available for a site. | +| [GET/sites/$site/post-counts/$post\_type](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/post-counts/%24post_type/) | Get number of posts in the post type groups by post status | +| [GET/sites/$site/widgets](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/widgets/) | Retrieve the active and inactive widgets for a site. | +| [POST/sites/$site/widgets/new](https://developer.wordpress.com/docs/api/1.1/post/sites/%24site/widgets/new/) | Activate a widget on a site. | +| [GET/sites/$site/wordads/settings](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/wordads/settings/) | Get detailed WordAds settings information about a site. | +| [POST/sites/$site/wordads/settings](https://developer.wordpress.com/docs/api/1.1/post/sites/%24site/wordads/settings/) | Update WordAds settings for a site. | +| [GET/sites/$site/wordads/earnings](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/wordads/earnings/) | Get detailed WordAds earnings information about a site. | +| [GET/sites/$site/wordads/tos](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/wordads/tos/) | Get WordAds TOS information about a site. | +| [POST/sites/$site/wordads/tos](https://developer.wordpress.com/docs/api/1.1/post/sites/%24site/wordads/tos/) | Update WordAds TOS setting for a site. | +| [POST/sites/$site/wordads/approve](https://developer.wordpress.com/docs/api/1.1/post/sites/%24site/wordads/approve/) | Request streamlined approval to join the WordAds program. | +| [GET/sites/$site/wordads/stats](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/wordads/stats/) | Get WordAds stats for a site | +| [GET/me/sites](https://developer.wordpress.com/docs/api/1.1/get/me/sites/) | Get a list of the current user’s sites. | +| [GET/me/sites/features](https://developer.wordpress.com/docs/api/1.1/get/me/sites/features/) | Get a list of the current user’s sites features | +| [GET/me/sites/plugins](https://developer.wordpress.com/docs/api/1.1/get/me/sites/plugins/) | Get a list of the current user’s sites plugins | +| [POST/sites/$site/search](https://developer.wordpress.com/docs/api/1.1/post/sites/%24site/search/) | Search within a site using an Elasticsearch Query API. | +| [GET/sites/$site/widgets/widget:$id](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/widgets/widget:%24id/) | Retrieve a widget on a site by its ID. | +| [POST/sites/$site/widgets/widget:$id](https://developer.wordpress.com/docs/api/1.1/post/sites/%24site/widgets/widget:%24id/) | Update a widget on a site by its ID. | +| [POST/sites/$site/widgets/widget:$id/delete](https://developer.wordpress.com/docs/api/1.1/post/sites/%24site/widgets/widget:%24id/delete/) | Deactivate a widget on a site by its ID. Will delete if already deactivated. | +| [GET/sites/$site/headers/$theme\_slug](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/headers/%24theme_slug/) | Get the custom header options for a site with a particular theme. | +| [GET/sites/$site/headers/mine](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/headers/mine/) | Get the custom header options for a site. | +| [POST/sites/$site/headers/mine](https://developer.wordpress.com/docs/api/1.1/post/sites/%24site/headers/mine/) | Set the custom header options for a site. | + +## Posts + +View and manage posts including reblogs and likes. + +| **Resource** | **Description** | +|---|---| +| [GET/sites/$site/dropdown-pages/](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/dropdown-pages/) | Get a list of pages to be displayed as options in a select-a-page-dropdown. | +| [GET/sites/$site/posts/$post\_ID](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/posts/%24post_ID/) | Get a single post (by ID). | +| [POST/sites/$site/posts/$post\_ID](https://developer.wordpress.com/docs/api/1.1/post/sites/%24site/posts/%24post_ID/) | Edit a post. | +| [GET/sites/$site/posts/slug:$post\_slug](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/posts/slug:%24post_slug/) | Get a single post (by slug). | +| [GET/sites/$site/posts/](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/posts/) | Get a list of matching posts. | +| [POST/sites/$site/posts/new](https://developer.wordpress.com/docs/api/1.1/post/sites/%24site/posts/new/) | Create a post. | +| [POST/sites/$site/posts/$post\_ID/delete](https://developer.wordpress.com/docs/api/1.1/post/sites/%24site/posts/%24post_ID/delete/) | Delete a post. Note: If the trash is enabled, this request will send the post to the trash. A second request will permanently delete the post. | +| [POST/sites/$site/posts/$post\_ID/restore](https://developer.wordpress.com/docs/api/1.1/post/sites/%24site/posts/%24post_ID/restore/) | Restore a post or page from the trash to its previous status. | +| [POST/sites/$site/posts/delete](https://developer.wordpress.com/docs/api/1.1/post/sites/%24site/posts/delete/) | Delete multiple posts. Note: If the trash is enabled, this request will send non-trashed posts to the trash. Trashed posts will be permanently deleted. | +| [POST/sites/$site/posts/restore](https://developer.wordpress.com/docs/api/1.1/post/sites/%24site/posts/restore/) | Restore multiple posts. | +| [GET/me/posts](https://developer.wordpress.com/docs/api/1.1/get/me/posts/) | Get a list of posts across all the user’s sites. | +| [GET/sites/$site/posts/$post\_ID/likes/](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/posts/%24post_ID/likes/) | Get a list of the likes for a post. | +| [POST/sites/$site/posts/$post\_ID/likes/new](https://developer.wordpress.com/docs/api/1.1/post/sites/%24site/posts/%24post_ID/likes/new/) | Like a post. | +| [POST/sites/$site/posts/$post\_ID/likes/mine/delete](https://developer.wordpress.com/docs/api/1.1/post/sites/%24site/posts/%24post_ID/likes/mine/delete/) | Unlike a post. | +| [GET/sites/$site/posts/$post\_ID/likes/mine/](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/posts/%24post_ID/likes/mine/) | Get the current user’s like status for a post. | +| [GET/sites/$site/posts/$post/subscribers/](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/posts/%24post/subscribers/) | Get a list of the specified post’s subscribers. | +| [GET/sites/$site/posts/$post/subscribers/mine](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/posts/%24post/subscribers/mine/) | Get subscription status of the specified post for the current user. | +| [POST/sites/$site/posts/$post/subscribers/new](https://developer.wordpress.com/docs/api/1.1/post/sites/%24site/posts/%24post/subscribers/new/) | Subscribe current user to be notified of the specified post’s comments. | +| [POST/sites/$site/posts/$post/subscribers/mine/update](https://developer.wordpress.com/docs/api/1.1/post/sites/%24site/posts/%24post/subscribers/mine/update/) | Subscribe current user to be notified of the specified post’s comments. | +| [POST/sites/$site/posts/$post/subscribers/mine/delete](https://developer.wordpress.com/docs/api/1.1/post/sites/%24site/posts/%24post/subscribers/mine/delete/) | Unsubscribe the current user from the specified post. | +| [POST/sites/$site/posts/$post\_ID/reblogs/new](https://developer.wordpress.com/docs/api/1.1/post/sites/%24site/posts/%24post_ID/reblogs/new/) | Reblog a post. | +| [GET/sites/$site/posts/$post\_ID/reblogs/mine](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/posts/%24post_ID/reblogs/mine/) | Get reblog status for a post. | +| [POST/sites/$site/posts/$post/related](https://developer.wordpress.com/docs/api/1.1/post/sites/%24site/posts/%24post/related/) | Search within a site for related posts. | + +## Comments + +View and manage a post’s comments. + +| **Resource** | **Description** | +|---|---| +| [GET/sites/$site/comments/$comment\_ID](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/comments/%24comment_ID/) | Get a single comment. | +| [POST/sites/$site/comments/$comment\_ID](https://developer.wordpress.com/docs/api/1.1/post/sites/%24site/comments/%24comment_ID/) | Edit a comment. | +| [GET/sites/$site/comments/](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/comments/) | Get a list of recent comments. | +| [GET/sites/$site/posts/$post\_ID/replies/](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/posts/%24post_ID/replies/) | Get a list of recent comments on a post. | +| [POST/sites/$site/posts/$post\_ID/replies/new](https://developer.wordpress.com/docs/api/1.1/post/sites/%24site/posts/%24post_ID/replies/new/) | Create a comment on a post. | +| [POST/sites/$site/comments/$comment\_ID/replies/new](https://developer.wordpress.com/docs/api/1.1/post/sites/%24site/comments/%24comment_ID/replies/new/) | Create a comment as a reply to another comment. | +| [POST/sites/$site/comments/$comment\_ID/delete](https://developer.wordpress.com/docs/api/1.1/post/sites/%24site/comments/%24comment_ID/delete/) | Delete a comment. | +| [GET/sites/$site/comment-counts](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/comment-counts/) | Get comment counts for each available status | +| [GET/sites/$site/comment-history/$comment\_ID](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/comment-history/%24comment_ID/) | Get the audit history for given comment | +| [GET/sites/$site/comments/$comment\_ID/likes/](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/comments/%24comment_ID/likes/) | Get the likes for a comment. | +| [POST/sites/$site/comments/$comment\_ID/likes/new](https://developer.wordpress.com/docs/api/1.1/post/sites/%24site/comments/%24comment_ID/likes/new/) | Like a comment. | +| [POST/sites/$site/comments/$comment\_ID/likes/mine/delete](https://developer.wordpress.com/docs/api/1.1/post/sites/%24site/comments/%24comment_ID/likes/mine/delete/) | Remove your like from a comment. | +| [GET/sites/$site/comments/$comment\_ID/likes/mine/](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/comments/%24comment_ID/likes/mine/) | Get your like status for a comment. | +| [GET/kill-switch/comment-likes](https://developer.wordpress.com/docs/api/1.1/get/kill-switch/comment-likes/) | Kill comment likes | + +## Taxonomy + +View and manage a site’s tags and categories. + +| **Resource** | **Description** | +|---|---| +| [GET/sites/$site/categories](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/categories/) | Get a list of a site’s categories. | +| [GET/sites/$site/tags](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/tags/) | Get a list of a site’s tags. | +| [GET/sites/$site/categories/slug:$category](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/categories/slug:%24category/) | Get information about a single category. | +| [POST/sites/$site/categories/slug:$category](https://developer.wordpress.com/docs/api/1.1/post/sites/%24site/categories/slug:%24category/) | Edit a category. | +| [GET/sites/$site/tags/slug:$tag](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/tags/slug:%24tag/) | Get information about a single tag. | +| [POST/sites/$site/tags/slug:$tag](https://developer.wordpress.com/docs/api/1.1/post/sites/%24site/tags/slug:%24tag/) | Edit a tag. | +| [GET/sites/$site/taxonomies/$taxonomy/terms/slug:$slug](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/taxonomies/%24taxonomy/terms/slug:%24slug/) | Get information about a single term. | +| [POST/sites/$site/taxonomies/$taxonomy/terms/slug:$slug](https://developer.wordpress.com/docs/api/1.1/post/sites/%24site/taxonomies/%24taxonomy/terms/slug:%24slug/) | Edit a term. | +| [GET/sites/$site/post-types/$post\_type/taxonomies](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/post-types/%24post_type/taxonomies/) | Get a list of taxonomies associated with a post type. | +| [GET/sites/$site/taxonomies/$taxonomy/terms](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/taxonomies/%24taxonomy/terms/) | Get a list of a site’s terms by taxonomy. | +| [POST/sites/$site/categories/new](https://developer.wordpress.com/docs/api/1.1/post/sites/%24site/categories/new/) | Create a new category. | +| [POST/sites/$site/tags/new](https://developer.wordpress.com/docs/api/1.1/post/sites/%24site/tags/new/) | Create a new tag. | +| [POST/sites/$site/categories/slug:$category/delete](https://developer.wordpress.com/docs/api/1.1/post/sites/%24site/categories/slug:%24category/delete/) | Delete a category. | +| [POST/sites/$site/tags/slug:$tag/delete](https://developer.wordpress.com/docs/api/1.1/post/sites/%24site/tags/slug:%24tag/delete/) | Delete a tag. | +| [POST/sites/$site/taxonomies/$taxonomy/terms/new](https://developer.wordpress.com/docs/api/1.1/post/sites/%24site/taxonomies/%24taxonomy/terms/new/) | Create a new term. | +| [POST/sites/$site/taxonomies/$taxonomy/terms/slug:$slug/delete](https://developer.wordpress.com/docs/api/1.1/post/sites/%24site/taxonomies/%24taxonomy/terms/slug:%24slug/delete/) | Delete a term. | + +## Follow + +Follow and unfollow blogs. + +| **Resource** | **Description** | +|---|---| +| [GET/sites/$site/follows/](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/follows/) | List a site’s followers in reverse chronological order. | +| [POST/sites/$site/follows/new](https://developer.wordpress.com/docs/api/1.1/post/sites/%24site/follows/new/) | Follow a blog. | +| [POST/sites/$site/follows/mine/delete](https://developer.wordpress.com/docs/api/1.1/post/sites/%24site/follows/mine/delete/) | Unfollow a blog. | +| [GET/sites/$site/follows/mine](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/follows/mine/) | Get blog following status for the current user. | + +## Sharing + +Connect social media services to automatically share new posts and manage sharing buttons on a site. + +| **Resource** | **Description** | +|---|---| +| [GET/sites/$site/sharing-buttons/](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/sharing-buttons/) | Get a list of a site’s sharing buttons. | +| [POST/sites/$site/sharing-buttons](https://developer.wordpress.com/docs/api/1.1/post/sites/%24site/sharing-buttons/) | Edit all sharing buttons for a site. | +| [GET/meta/external-services/](https://developer.wordpress.com/docs/api/1.1/get/meta/external-services/) | Get a list of third-party services that WordPress.com or Jetpack sites can integrate with via keyring. | +| [GET/meta/external-services/$service](https://developer.wordpress.com/docs/api/1.1/get/meta/external-services/%24service/) | Get information about a single external service that WordPress.com or Jetpack sites can integrate with via keyring. | +| [GET/me/publicize-connections/](https://developer.wordpress.com/docs/api/1.1/get/me/publicize-connections/) | Get a list of publicize connections that the current user has set up. | +| [GET/me/publicize-connections/$publicize\_connection\_ID](https://developer.wordpress.com/docs/api/1.1/get/me/publicize-connections/%24publicize_connection_ID/) | Get a single publicize connection that the current user has set up. | +| [POST/me/publicize-connections/$publicize\_connection\_ID](https://developer.wordpress.com/docs/api/1.1/post/me/publicize-connections/%24publicize_connection_ID/) | Update a single publicize connection belonging to the current user. | +| [POST/me/publicize-connections/$publicize\_connection\_ID/delete](https://developer.wordpress.com/docs/api/1.1/post/me/publicize-connections/%24publicize_connection_ID/delete/) | Delete the specified publicize connection. | +| [GET/me/keyring-connections/](https://developer.wordpress.com/docs/api/1.1/get/me/keyring-connections/) | Get a list of all the keyring connections associated with the current user. | +| [GET/me/keyring-connections/$keyring\_connection\_ID](https://developer.wordpress.com/docs/api/1.1/get/me/keyring-connections/%24keyring_connection_ID/) | Get a single Keyring connection that the current user has setup. | +| [POST/me/keyring-connections/$keyring\_connection\_ID/delete](https://developer.wordpress.com/docs/api/1.1/post/me/keyring-connections/%24keyring_connection_ID/delete/) | Delete the Keyring connection (and associated token) with the provided ID. Also deletes all associated publicize connections. | +| [GET/sites/$site/publicize-connections/](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/publicize-connections/) | Get a list of publicize connections that are associated with the specified site. | +| [GET/sites/$site/publicize-connections/$publicize\_connection\_ID](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/publicize-connections/%24publicize_connection_ID/) | Get a single publicize connection that is associated with the specified site. | +| [POST/sites/$site/publicize-connections/$publicize\_connection\_ID](https://developer.wordpress.com/docs/api/1.1/post/sites/%24site/publicize-connections/%24publicize_connection_ID/) | Update a single publicize connection belonging to the specified site. | +| [POST/sites/$site/publicize-connections/new](https://developer.wordpress.com/docs/api/1.1/post/sites/%24site/publicize-connections/new/) | Create a new publicize connection that is associated with the specified site. | +| [POST/sites/$site/publicize-connections/$publicize\_connection\_ID/delete](https://developer.wordpress.com/docs/api/1.1/post/sites/%24site/publicize-connections/%24publicize_connection_ID/delete/) | Delete the specified publicize connection. | +| [GET/meta/sharing-buttons](https://developer.wordpress.com/docs/api/1.1/get/meta/sharing-buttons/) | Get a list of external services for which sharing buttons are supported. | + +## Freshly Pressed + +View Freshly Pressed posts from the WordPress.com homepage. + +| **Resource** | **Description** | +|---|---| +| [GET/freshly-pressed/](https://developer.wordpress.com/docs/api/1.1/get/freshly-pressed/) | Get a list of Freshly Pressed posts. (Note: Freshly Pressed has been retired. Please visit [https://discover.wordpress.com](https://discover.wordpress.com/) to get the best content published across our network.) | + +## Notifications + +View and manage a user’s notifications. + +| **Resource** | **Description** | +|---|---| +| [POST/notifications/seen](https://developer.wordpress.com/docs/api/1.1/post/notifications/seen/) | Set the timestamp of the most recently seen notification. | +| [POST/notifications/read](https://developer.wordpress.com/docs/api/1.1/post/notifications/read/) | Mark a set of notifications as read. | + +## Insights + +View analytics for your application. + +| **Resource** | **Description** | +|---|---| +| [GET/insights](https://developer.wordpress.com/docs/api/1.1/get/insights/) | Get a list of stats/metrics/insights that the current user has access to. | +| [GET/insights/$slug](https://developer.wordpress.com/docs/api/1.1/get/insights/%24slug/) | Get raw data for a particular graph. | + +## Reader + +Manage and view a user’s subscriptions to the WordPress.com Reader. + +| **Resource** | **Description** | +|---|---| +| [GET/read/menu/](https://developer.wordpress.com/docs/api/1.1/get/read/menu/) | Get default reader menu. | +| [GET/read/feed/$feed\_url\_or\_id](https://developer.wordpress.com/docs/api/1.1/get/read/feed/%24feed_url_or_id/) | Get details about a feed. | +| [GET/read/sites/$site/posts/$post\_ID](https://developer.wordpress.com/docs/api/1.1/get/read/sites/%24site/posts/%24post_ID/) | Get a single post (by ID). | +| [GET/read/following/](https://developer.wordpress.com/docs/api/1.1/get/read/following/) | Get a list of posts from the blogs a user follows. | +| [GET/read/liked/](https://developer.wordpress.com/docs/api/1.1/get/read/liked/) | Get a list of posts from the blogs a user likes. | +| [GET/read/tags/$tag/posts](https://developer.wordpress.com/docs/api/1.1/get/read/tags/%24tag/posts/) | Get a list of posts from a tag. | +| [GET/read/tags](https://developer.wordpress.com/docs/api/1.1/get/read/tags/) | Get a list of tags subscribed to by the user. | +| [GET/read/tags/alphabetic](https://developer.wordpress.com/docs/api/1.1/get/read/tags/alphabetic/) | Get a filtered list of top tags, grouped by letter. | +| [GET/read/trending/tags](https://developer.wordpress.com/docs/api/1.1/get/read/trending/tags/) | Get a list of trending tags. | +| [GET/read/tags/$tag](https://developer.wordpress.com/docs/api/1.1/get/read/tags/%24tag/) | Get details about a specified tag. | +| [GET/read/tags/$tag/mine](https://developer.wordpress.com/docs/api/1.1/get/read/tags/%24tag/mine/) | Get the subscribed status of the user to a given tag. | +| [POST/read/tags/$tag/mine/new](https://developer.wordpress.com/docs/api/1.1/post/read/tags/%24tag/mine/new/) | Subscribe to a new tag. | +| [POST/read/tags/$tag/mine/delete](https://developer.wordpress.com/docs/api/1.1/post/read/tags/%24tag/mine/delete/) | Unsubscribe from a tag. | +| [GET/read/following/mine](https://developer.wordpress.com/docs/api/1.1/get/read/following/mine/) | Get a list of the feeds the user is following. | +| [POST/read/following/mine/new](https://developer.wordpress.com/docs/api/1.1/post/read/following/mine/new/) | Follow the specified blog. | +| [POST/read/following/mine/delete](https://developer.wordpress.com/docs/api/1.1/post/read/following/mine/delete/) | Unfollow the specified blog. | +| [GET/read/feed/](https://developer.wordpress.com/docs/api/1.1/get/read/feed/) | Get the ID and subscribe URL of one or more matching feeds by domain or URL. | +| [GET/read/email-settings/](https://developer.wordpress.com/docs/api/1.1/get/read/email-settings/) | Returns the email settings | +| [POST/read/email-settings/](https://developer.wordpress.com/docs/api/1.1/post/read/email-settings/) | Returns the email settings | +| [GET/read/subscriptions-count/](https://developer.wordpress.com/docs/api/1.1/get/read/subscriptions-count/) | Returns the number of blog, comment and pending subscriptions. | +| [GET/read/recommendations/mine/](https://developer.wordpress.com/docs/api/1.1/get/read/recommendations/mine/) | Get a list of blog recommendations for the current user. | + +## Stats + +View stats for a site. + +| **Resource** | **Description** | +|---|---| +| [GET/sites/$site/stats/highlights](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/stats/highlights/) | View highlight metrics from the last seven days. | +| [GET/sites/$site/stats](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/stats/) | Get a site’s stats | +| [GET/sites/$site/stats/summary](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/stats/summary/) | View a site’s summarized views, visitors, likes and comments | +| [GET/sites/$site/stats/top-posts](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/stats/top-posts/) | View a site’s top posts and pages by views | +| [GET/sites/$site/stats/video/$post\_id](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/stats/video/%24post_id/) | View the details of a single video | +| [GET/sites/$site/stats/referrers](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/stats/referrers/) | View a site’s referrers | +| [GET/sites/$site/stats/clicks](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/stats/clicks/) | View a site’s outbound clicks | +| [GET/sites/$site/stats/tags](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/stats/tags/) | View a site’s views by tags and categories | +| [GET/sites/$site/stats/top-authors](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/stats/top-authors/) | View a site’s top authors | +| [GET/sites/$site/stats/comments](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/stats/comments/) | View a site’s top comment authors and most-commented posts | +| [GET/sites/$site/stats/video-plays](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/stats/video-plays/) | View a site’s video plays | +| [GET/sites/$site/stats/file-downloads](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/stats/file-downloads/) | View a site’s file downloads | +| [GET/sites/$site/stats/post/$post\_id](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/stats/post/%24post_id/) | View a post’s views | +| [GET/sites/$site/stats/country-views](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/stats/country-views/) | View a site’s views by country | +| [GET/sites/$site/stats/followers](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/stats/followers/) | View a site’s followers | +| [GET/sites/$site/stats/comment-followers](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/stats/comment-followers/) | View a site’s comment followers | +| [POST/sites/$site/stats/referrers/spam/new](https://developer.wordpress.com/docs/api/1.1/post/sites/%24site/stats/referrers/spam/new/) | Report a referrer as spam | +| [POST/sites/$site/stats/referrers/spam/delete](https://developer.wordpress.com/docs/api/1.1/post/sites/%24site/stats/referrers/spam/delete/) | Unreport a referrer as spam | +| [GET/sites/$site/stats/publicize](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/stats/publicize/) | View a site’s publicize follower counts | +| [GET/sites/$site/stats/search-terms](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/stats/search-terms/) | View search terms used to find the site | +| [GET/sites/$site/stats/views/posts](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/stats/views/posts/) | View the total number of views for each post. | +| [GET/sites/$site/stats/emails/summary](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/stats/emails/summary/) | View the total number of email opens and clicks for each post. | +| [GET/sites/$site/stats/opens/emails/summary](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/stats/opens/emails/summary/) | View the total number of email opens for each post. | +| [GET/sites/$site/stats/opens/emails/$post\_id](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/stats/opens/emails/%24post_id/) | View multiple stats related to email opens by post. | +| [GET/sites/$site/stats/opens/emails/$post\_id/client](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/stats/opens/emails/%24post_id/client/) | View email opens stats by client. | +| [GET/sites/$site/stats/opens/emails/$post\_id/country](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/stats/opens/emails/%24post_id/country/) | View email opens stats by country. | +| [GET/sites/$site/stats/opens/emails/$post\_id/device](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/stats/opens/emails/%24post_id/device/) | View email opens stats by device. | +| [GET/sites/$site/stats/opens/emails/$post\_id/rate](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/stats/opens/emails/%24post_id/rate/) | View email opens rate by post. | +| [GET/sites/$site/stats/clicks/emails/$post\_id](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/stats/clicks/emails/%24post_id/) | View chart stats related to email clicks by period. | +| [GET/sites/$site/stats/clicks/emails/$post\_id/rate](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/stats/clicks/emails/%24post_id/rate/) | View email clicks rate by post. Returns mock data. | +| [GET/sites/$site/stats/clicks/emails/$post\_id/country](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/stats/clicks/emails/%24post_id/country/) | View email clicks by country. | +| [GET/sites/$site/stats/clicks/emails/$post\_id/device](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/stats/clicks/emails/%24post_id/device/) | View email clicks by device. | +| [GET/sites/$site/stats/clicks/emails/$post\_id/client](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/stats/clicks/emails/%24post_id/client/) | View email clicks by client. | +| [GET/sites/$site/stats/clicks/emails/$post\_id/link](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/stats/clicks/emails/%24post_id/link/) | View email clicks by link. | +| [GET/sites/$site/stats/clicks/emails/$post\_id/user-content-link](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/stats/clicks/emails/%24post_id/user-content-link/) | View email clicks by user content link. | +| [GET/sites/$site/stats/clicks/emails/summary](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/stats/clicks/emails/summary/) | View the total number of email clicks for each post. | +| [GET/sites/$site/stats/utm/$utm\_param\_name](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/stats/utm/%24utm_param_name/) | Fetch site’s UTM param statistics. | +| [GET/sites/$site/stats/utm/$utm\_param\_name/top\_posts](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/stats/utm/%24utm_param_name/top_posts/) | Fetch top posts for a given UTM parameter value. | +| [GET/sites/$site/stats/streak](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/stats/streak/) | Get stats for Calendar Heatmap. Returns data with each post timestamp. | + +## Media + +Manage a site’s media library. + +| **Resource** | **Description** | +|---|---| +| [POST/sites/$site/media/$media\_ID/delete](https://developer.wordpress.com/docs/api/1.1/post/sites/%24site/media/%24media_ID/delete/) | Delete a piece of media. Note: Media is deleted and not trashed. | +| [GET/sites/$site/media/$media\_ID](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/media/%24media_ID/) | Get a single media item (by ID). | +| [POST/sites/$site/media/$media\_ID](https://developer.wordpress.com/docs/api/1.1/post/sites/%24site/media/%24media_ID/) | Edit basic information about a media item. | +| [GET/sites/$site/media/](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/media/) | Get a list of items in the media library. | +| [POST/sites/$site/media/new](https://developer.wordpress.com/docs/api/1.1/post/sites/%24site/media/new/) | Upload a new piece of media. | +| [POST/sites/$site/media/$media\_ID/edit](https://developer.wordpress.com/docs/api/1.1/post/sites/%24site/media/%24media_ID/edit/) | Edit a media item. | + +## Menus + +View and manage a site’s menus. + +| **Resource** | **Description** | +|---|---| +| [POST/sites/$site/menus/new](https://developer.wordpress.com/docs/api/1.1/post/sites/%24site/menus/new/) | Create a new navigation menu. | +| [POST/sites/$site/menus/$menu\_id](https://developer.wordpress.com/docs/api/1.1/post/sites/%24site/menus/%24menu_id/) | Update a navigation menu. | +| [GET/sites/$site/menus/$menu\_id](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/menus/%24menu_id/) | Get a single navigation menu. | +| [GET/sites/$site/menus](https://developer.wordpress.com/docs/api/1.1/get/sites/%24site/menus/) | Get a list of all navigation menus. | +| [POST/sites/$site/menus/$menu\_id/delete](https://developer.wordpress.com/docs/api/1.1/post/sites/%24site/menus/%24menu_id/delete/) | Delete a navigation menu | + +## Batch + +Batch several API GET requests into one. + +| **Resource** | **Description** | +|---|---| +| [GET/batch/](https://developer.wordpress.com/docs/api/1.1/get/batch/) | Run several GET endpoints and return them as an array. | + +## Videos + +View video information. + +| **Resource** | **Description** | +|---|---| +| [GET/videos/$guid](https://developer.wordpress.com/docs/api/1.1/get/videos/%24guid/) | Get the metadata for a specified VideoPress video. | +| [GET/videos/$guid/poster](https://developer.wordpress.com/docs/api/1.1/get/videos/%24guid/poster/) | Get the poster for a specified VideoPress video. | +| [POST/videos/$guid/poster](https://developer.wordpress.com/docs/api/1.1/post/videos/%24guid/poster/) | Upload and set a poster for a specified VideoPress video. | +| [GET/videos/$guid/chapters](https://developer.wordpress.com/docs/api/1.1/get/videos/%24guid/chapters/) | Get the chapters for a specified VideoPress video. | +| [GET/videos/$guid/playlist/$format](https://developer.wordpress.com/docs/api/1.1/get/videos/%24guid/playlist/%24format/) | Get the poster for a specified VideoPress video. | +| [POST/videos/$guid/tracks](https://developer.wordpress.com/docs/api/1.1/post/videos/%24guid/tracks/) | Upload a subtitle/caption track for a specified VideoPress video. | +| [POST/videos/$guid/tracks/delete](https://developer.wordpress.com/docs/api/1.1/post/videos/%24guid/tracks/delete/) | Delete an existing subtitle/caption track for a specified VideoPress video. | + +## Agencies + +Manage agency sites and tools. + +| **Resource** | **Description** | +|---|---| +| [GET /wpcom/v2/agency/$agency\_id/sites](https://developer.wordpress.com/docs/api/2/get/agency/$agency_id/sites/) | Get a list of sites managed by the agency. | +| [GET/wpcom/v2/agency/$agency\_id/sites/pending](https://developer.wordpress.com/docs/api/2/get/agency/$agency_id/sites/pending/) | Get a list of sites that are available for provision. | +| [POST/wpcom/v2/agency/$agency\_id/sites/$site\_id/provision](https://developer.wordpress.com/docs/api/2/post/agency/$agency_id/sites/$site_id/provision/) | Provision of a new site for the agency. | +| [GET/wpcom/v2/sites/$wpcom\_site/staging-site](https://developer.wordpress.com/docs/api/2/get/sites/$wpcom_site/staging-site/) | Retrieves the staging site associated with a specified production site. | +| [POST/wpcom/v2/sites/$wpcom\_site/staging-site](https://developer.wordpress.com/docs/api/2/post/sites/$wpcom_site/staging-site/) | Creates a [staging site](https://wordpress.com/support/how-to-create-a-staging-site/) for an existing site. | +| [DELETE/wpcom/v2/sites/$wpcom\_site/staging-site/$staging\_site\_id](https://developer.wordpress.com/docs/api/2/delete/sites/$wpcom_site/staging-site/$staging_site_id/) | Deletes the staging site associated with the specified production site. | +| [GET/sites/$site/automated-transfers/status](https://developer.wordpress.com/docs/api/1.1/get/sites/$site/automated-transfers/status/) | Returns the current status of Automated Transfer for a site. | + +## GitHub Deployments + +Deploy code on WordPress.com infrastructure. + +| **Resource** | **Description** | +|---|---| +| [GET/hosting/github/installations](https://developer.wordpress.com/docs/api/2/get/hosting/github/installations/) | Return a list of installations that a GitHub user has access to through app installations. | +| [GET/hosting/github/repositories](https://developer.wordpress.com/docs/api/2/get/hosting/github/repositories/) | Get a list of repositories and their external\_repository\_ids. | +| [GET/sites/$wpcom\_site/hosting/code-deployments](https://developer.wordpress.com/docs/api/2/get/sites/$wpcom_site/hosting/code-deployments/) | Get a list of site code deployments configured for this site. | +| [POST/sites/$wpcom\_site/hosting/code-deployments](https://developer.wordpress.com/docs/api/2/post/sites/$wpcom_site/hosting/code-deployments/) | Create or update a deployment configuration for this site. | +| [DELETE/wpcom/v2/sites/$wpcom\_site/hosting/code-deployments/$deployment\_id](https://developer.wordpress.com/docs/api/2/delete/sites/$wpcom_site/hosting/code-deployments/$deployment_id/) | Delete a deployment configuration for a site. | +| [GET/wpcom/v2/sites/$wpcom\_site/hosting/code-deployments/$deployment\_id/runs](https://developer.wordpress.com/docs/api/2/get/sites/$wpcom_site/hosting/code-deployments/$deployment_id/runs/) | Get code deployment runs. | +| [POST/sites/$wpcom\_site/hosting/code-deployments/$deployment\_id/runs](https://developer.wordpress.com/docs/api/2/post/sites/$wpcom_site/hosting/code-deployments/$deployment_id/runs/) | Initiate a manual deployment run of a code using its deployment\_id. | +| [GET/sites/$wpcom\_site/hosting/code-deployments/$deployment\_id/](https://developer.wordpress.com/docs/api/2/get/sites/$wpcom_site/hosting/code-deployments/$deployment_id/runs/$deployment_run_id/logs/) [runs/$deployment\_run\_id/logs](https://developer.wordpress.com/docs/api/2/get/sites/$wpcom_site/hosting/code-deployments/$deployment_id/runs/$deployment_run_id/logs/) | Get the logs for a deployment run of a code using its deployment\_id and deployment\_run\_id. | + +## SSH Management + +Create and manage SSH access to WordPress.com servers. + +| **Resource** | **Description** | +|---|---| +| [GET/wpcom/v2/sites/$wpcom\_site/hosting/ssh-users](https://developer.wordpress.com/docs/api/2/get/sites/$wpcom_site/hosting/ssh-users/) | Get SSH users for a site. | +| [POST/wpcom/v2/sites/$wpcom\_site/hosting/ssh-user](https://developer.wordpress.com/docs/api/2/post/sites/$wpcom_site/hosting/ssh-user/) | Create an SSH user for a site. | +| [POST/wpcom/v2/sites/$wpcom\_site/hosting/ssh-user/$ssh\_user/reset-password](https://developer.wordpress.com/docs/api/2/post/sites/$wpcom_site/hosting/ssh-user/$ssh_user/reset-password/) | Rotate the SSH user password and return it. | +| [GET/wpcom/v2/sites/$wpcom\_site/hosting/ssh-access](https://developer.wordpress.com/docs/api/2/get/sites/$wpcom_site/hosting/ssh-access/) | Gets the SSH access setting type for a site. | +| [POST/wpcom/v2/sites/$wpcom\_site/hosting/ssh-access](https://developer.wordpress.com/docs/api/2/post/sites/$wpcom_site/hosting/ssh-access/) | Sets the SSH access setting for a site. | +| [GET/wpcom/v2/sites/$wpcom\_site/hosting/ssh-keys](https://developer.wordpress.com/docs/api/2/get/sites/$wpcom_site/hosting/ssh-keys/) | Get SSH keys for a site. | +| [POST/wpcom/v2/sites/$wpcom\_site/hosting/ssh-keys](https://developer.wordpress.com/docs/api/2/post/sites/$wpcom_site/hosting/ssh-keys/) | Attach a new SSH key to a site. | +| [DELETE/wpcom/v2/sites/$wpcom\_site/hosting/ssh-keys/$user\_name/$name](https://developer.wordpress.com/docs/api/2/delete/sites/$wpcom_site/hosting/ssh-keys/$user_name/$name/) | Detach an SSH key from a site. | diff --git a/content/runtime/documentation/api/wpcc.md b/content/runtime/documentation/api/wpcc.md new file mode 100644 index 0000000..34bca35 --- /dev/null +++ b/content/runtime/documentation/api/wpcc.md @@ -0,0 +1,317 @@ +--- +type: document +title: WordPress.com Connect +description: "" +resource: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/wpcc/" +tags: +timestamp: "2026-06-16T19:29:26+00:00" +wordpress: + id: 2489 + status: publish + type: documentation + author: 0 + date: "2026-06-16 19:29:26" + date_gmt: "2026-06-16 19:29:26" + modified: "2026-06-16 19:29:30" + modified_gmt: "2026-06-16 19:29:30" + slug: wpcc + parent: 2499 + menu_order: 0 + comment_status: closed + ping_status: closed + guid: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/wpcc/" + comment_count: 0 +--- + +WordPress.com Connect is a streamlined authentication solution designed specifically for **“Login with WordPress.com”** functionality. It provides a secure and user-friendly way for millions of WordPress.com users to authenticate with your application using their existing WordPress.com credentials. + +![Image showing the Connect with WordPress.com button.](//s0.wp.com/i/wpcc-button.png)WordPress.com Connect is a specialized implementation of OAuth2 focused on user authentication and identity verification. For full API access to WordPress.com sites and content management, see the complete [OAuth2 Authentication](https://developer.wordpress.com/docs/api/oauth2) documentation. + +WordPress.com Connect allows WordPress.com users to quickly log in to your service without creating new accounts. When users connect, your application receives their basic profile information (name, email, avatar) while they maintain control over their WordPress.com data and privacy. + +**Key characteristics of WordPress.com Connect**: + +- **User-friendly**: Familiar interface for millions of WordPress.com users +- **Identity-focused**: Designed for user authentication, not content management +- **Limited scope**: Access restricted to basic profile information via the `/me/` endpoint +- **Simplified flow**: Optimized for “Login with WordPress.com” buttons + +## Benefits + +**Millions Of Users** – WordPress.com consists of millions of users and is growing every day. By adding WordPress.com Connect you will become part of a large family that makes it easy for WordPress.com users to explore new services. + +**Compatible with your existing sign-in system** – WordPress.com Connect can be used on its own or as a complimentary sign-in option to your existing registration system. Once a user connects, you will get access to their profile information which you can use in your own app. + +**Trusted Relationship** – Allow users to sign-in with the same credentials they use every day on WordPress.com. This takes the pain out of having to remember and manage a new log-in for another service. + + For practical implementation examples of WordPress.com Connect in different programming languages, check out the [wpcom-connect-examples repository](https://github.com/Automattic/wpcom-connect-examples). This repository contains sample code demonstrating how to implement “Login with WordPress.com” functionality across various languages and frameworks. + +## OAuth2 Implementation Details + +WordPress.com Connect uses the **OAuth2 Authentication Endpoint** (`/oauth2/authenticate`) rather than the standard authorization endpoint. This specialized endpoint is optimized for identity verification and automatically limits token scope to basic profile access. + +**Technical Flow**: + +1. **User Authorization**: Redirect to `/oauth2/authenticate` (not `/oauth2/authorize`) +2. **Code Exchange**: Exchange authorization code at `/oauth2/token` (same as full OAuth2) +3. **Limited Access**: Resulting token provides access only to `/me/` endpoint +4. **Profile Data**: Retrieve user identity from `/rest/v1.1/me` + + For detailed technical information about the `/oauth2/authenticate` endpoint, see the [Authentication Endpoint section](https://developer.wordpress.com/docs/api/oauth2/#Authentication-Endpoint) in the OAuth2 documentation. + +## Prerequisites + +Before implementing WordPress.com Connect, you need to register your application: + +1. **Create a WordPress.com Application** at [developer.wordpress.com/apps](https://developer.wordpress.com/apps/) +2. **Configure your application**: Use the same title as your website (shown in login forms) +3. **Obtain credentials**: You’ll receive a `CLIENT_ID` and `CLIENT_SECRET` +4. **Set redirect URI**: Configure where users return after authentication + +## Implementation Example (PHP) + +Here’s a complete example demonstrating how to implement WordPress.com Connect for user authentication and profile retrieval. + +### Configuration Setup + +First, configure your application credentials. Replace these values with those from your [WordPress.com Application](https://developer.wordpress.com/apps/): + +``` + +``` + +<?php // config.php - WordPress.com Connect Configuration define('CLIENT\_ID', 'your\_client\_id'); define('CLIENT\_SECRET', 'your\_client\_secret'); define('REDIRECT\_URI', 'https://yourapp.com/auth-callback'); // WordPress.com OAuth2 endpoints (no changes needed) define('AUTHENTICATE\_URL', 'https://public-api.wordpress.com/oauth2/authenticate'); define('TOKEN\_URL', 'https://public-api.wordpress.com/oauth2/token'); define('USER\_INFO\_URL', 'https://public-api.wordpress.com/rest/v1.1/me'); session\_start(); // Required for state parameter security ?>CopyCopied + + **Complete example**: See the [wpcom-connect-examples repository](https://github.com/Automattic/wpcom-connect-examples/blob/master/php/config.php) for additional language implementations. + +### Step 1: Create Authorization URL + +Generate the “Connect with WordPress.com” button that redirects users to WordPress.com for authentication. This uses the **authentication endpoint** (not the standard authorization endpoint). + +**Security Note**: The `state` parameter prevents CSRF attacks and must be validated when users return. + +``` + 'code', + 'client_id' => CLIENT_ID, + 'redirect_uri' => REDIRECT_URI, + 'state' => $_SESSION['wpcc_state'], + 'scope' => 'auth' // Limited scope for profile access only +]); + +// Display the Connect button +echo ''; +echo 'Connect with WordPress.com'; +echo ''; +?> +``` + +<?php require\_once 'config.php'; // Generate secure state parameter for CSRF protection if (!isset($\_SESSION\['wpcc\_state'\])) { $\_SESSION\['wpcc\_state'\] = bin2hex(random\_bytes(16)); // More secure than md5(mt\_rand()) } // Build authentication URL using /oauth2/authenticate endpoint $auth\_url = AUTHENTICATE\_URL . '?' . http\_build\_query(\[ 'response\_type' => 'code', 'client\_id' => CLIENT\_ID, 'redirect\_uri' => REDIRECT\_URI, 'state' => $\_SESSION\['wpcc\_state'\], 'scope' => 'auth' // Limited scope for profile access only \]); // Display the Connect button echo '<a href="' . htmlspecialchars($auth\_url) . '">'; echo '<img src="https://s0.wp.com/i/wpcc-button.png" width="231" alt="Connect with WordPress.com" />'; echo '</a>'; ?>CopyCopied + +This generates the familiar WordPress.com Connect button: + +![Image showing the Connect with WordPress.com button.](https://s0.wp.com/i/wpcc-button.png)### Step 2: Handle Authorization Response + +When users click the Connect button, they see a WordPress.com authorization screen: + +![WordPress login prompt asking users to approve access for Test Company, detailing information that will be viewed, with options to approve or deny.](https://wpdeveloperstaging.files.wordpress.com/2024/02/e124d-oauth-approve.png)After approval, WordPress.com redirects users back to your `redirect_uri` with an authorization code. Your callback handler must validate the state parameter and exchange the code for an access token: + +``` + true, + CURLOPT_POSTFIELDS => [ + 'client_id' => CLIENT_ID, + 'client_secret' => CLIENT_SECRET, + 'code' => $_GET['code'], + 'grant_type' => 'authorization_code', + 'redirect_uri' => REDIRECT_URI + ], + CURLOPT_RETURNTRANSFER => true, + CURLOPT_SSL_VERIFYPEER => true +]); + +$response = curl_exec($curl); +$http_code = curl_getinfo($curl, CURLINFO_HTTP_CODE); +curl_close($curl); + +if ($http_code !== 200) { + die('Error: Failed to obtain access token.'); +} + +$token_data = json_decode($response, true); +$access_token = $token_data['access_token']; + +// Clean up session state +unset($_SESSION['wpcc_state']); +?> +``` + +<?php // auth-callback.php - Handle the authorization response require\_once 'config.php'; // Validate authorization response if (!isset($\_GET\['code'\])) { die('Error: No authorization code received. User may have declined access.'); } if (!isset($\_GET\['state'\]) || $\_GET\['state'\] !== $\_SESSION\['wpcc\_state'\]) { die('Error: State mismatch. Possible CSRF attack detected.'); } // Exchange authorization code for access token $curl = curl\_init(TOKEN\_URL); curl\_setopt\_array($curl, \[ CURLOPT\_POST => true, CURLOPT\_POSTFIELDS => \[ 'client\_id' => CLIENT\_ID, 'client\_secret' => CLIENT\_SECRET, 'code' => $\_GET\['code'\], 'grant\_type' => 'authorization\_code', 'redirect\_uri' => REDIRECT\_URI \], CURLOPT\_RETURNTRANSFER => true, CURLOPT\_SSL\_VERIFYPEER => true \]); $response = curl\_exec($curl); $http\_code = curl\_getinfo($curl, CURLINFO\_HTTP\_CODE); curl\_close($curl); if ($http\_code !== 200) { die('Error: Failed to obtain access token.'); } $token\_data = json\_decode($response, true); $access\_token = $token\_data\['access\_token'\]; // Clean up session state unset($\_SESSION\['wpcc\_state'\]); ?>CopyCopied + +**Successful token response**: + +``` +{ + "access_token": "your_access_token_here", + "token_type": "bearer", + "blog_id": 0, + "blog_url": "https://public-api.wordpress.com", + "scope": "auth" +} +``` + +{ "access\_token": "your\_access\_token\_here", "token\_type": "bearer", "blog\_id": 0, "blog\_url": "https://public-api.wordpress.com", "scope": "auth" }CopyCopied + +Note the `scope: "auth"` – this confirms the token has limited access for identity verification only. + +### Step 3: Retrieve User Profile + +With the access token, retrieve the user’s profile information from the [`/me/` endpoint](https://developer.wordpress.com/docs/api/1/get/me/): + +``` + [ + 'Authorization: Bearer ' . $access_token + ], + CURLOPT_RETURNTRANSFER => true, + CURLOPT_SSL_VERIFYPEER => true // Always verify SSL in production + ]); + + $response = curl_exec($curl); + $http_code = curl_getinfo($curl, CURLINFO_HTTP_CODE); + curl_close($curl); + + if ($http_code !== 200) { + throw new Exception('Failed to fetch user profile'); + } + + return json_decode($response, true); +} + +// Get the user's WordPress.com profile +try { + $user_profile = get_user_profile($access_token); + + // Store or process user information + $user_id = $user_profile['ID']; + $display_name = $user_profile['display_name']; + $email = $user_profile['email']; + $avatar_url = $user_profile['avatar_URL']; + $is_verified = $user_profile['verified']; + +} catch (Exception $e) { + die('Error: ' . $e->getMessage()); +} +?> +``` + +<?php // Fetch user profile using the access token function get\_user\_profile($access\_token) { $curl = curl\_init(USER\_INFO\_URL); curl\_setopt\_array($curl, \[ CURLOPT\_HTTPHEADER => \[ 'Authorization: Bearer ' . $access\_token \], CURLOPT\_RETURNTRANSFER => true, CURLOPT\_SSL\_VERIFYPEER => true // Always verify SSL in production \]); $response = curl\_exec($curl); $http\_code = curl\_getinfo($curl, CURLINFO\_HTTP\_CODE); curl\_close($curl); if ($http\_code !== 200) { throw new Exception('Failed to fetch user profile'); } return json\_decode($response, true); } // Get the user's WordPress.com profile try { $user\_profile = get\_user\_profile($access\_token); // Store or process user information $user\_id = $user\_profile\['ID'\]; $display\_name = $user\_profile\['display\_name'\]; $email = $user\_profile\['email'\]; $avatar\_url = $user\_profile\['avatar\_URL'\]; $is\_verified = $user\_profile\['verified'\]; } catch (Exception $e) { die('Error: ' . $e->getMessage()); } ?>CopyCopied + +**Profile response format**: + +``` +{ + "ID": 12345, + "display_name": "Bob Smith", + "username": "bobsmith", + "email": "bob@example.com", + "primary_blog": 67890, + "avatar_URL": "https://gravatar.com/avatar/abc123?s=96", + "profile_URL": "https://en.gravatar.com/bobsmith", + "verified": true +} +``` + +{ "ID": 12345, "display\_name": "Bob Smith", "username": "bobsmith", "email": "bob@example.com", "primary\_blog": 67890, "avatar\_URL": "https://gravatar.com/avatar/abc123?s=96", "profile\_URL": "https://en.gravatar.com/bobsmith", "verified": true }CopyCopied + +### Step 4: Complete User Authentication + +Once you have the user profile, integrate them into your application: + +``` + $user_id, + 'username' => $user_profile['username'], + 'email' => $email, + 'display_name' => $display_name, + 'avatar_url' => $avatar_url + ]); + login_user($new_user); + redirect_to_welcome(); + } +} else { + // Unverified email - handle with caution + redirect_to_verification_required(); +} +?> +``` + +<?php // Complete user authentication flow if ($is\_verified) { // User has verified their email - safe to trust profile data $existing\_user = find\_user\_by\_wpcom\_id($user\_id); if ($existing\_user) { // Log in existing user login\_user($existing\_user); redirect\_to\_dashboard(); } else { // Create new account with WordPress.com profile data $new\_user = create\_user(\[ 'wpcom\_id' => $user\_id, 'username' => $user\_profile\['username'\], 'email' => $email, 'display\_name' => $display\_name, 'avatar\_url' => $avatar\_url \]); login\_user($new\_user); redirect\_to\_welcome(); } } else { // Unverified email - handle with caution redirect\_to\_verification\_required(); } ?>CopyCopied + +**Important**: Always check the `verified` flag before trusting profile information. Unverified accounts may contain unreliable data. + +## WordPress.com Connect vs Full OAuth2 + +Understanding when to use each approach: + +| Feature | WordPress.com Connect | Full OAuth2 | +|---|---|---| +| **Purpose** | User authentication & identity | Full API access & content management | +| **Endpoint** | `/oauth2/authenticate` | `/oauth2/authorize` | +| **Token Scope** | `auth` (limited to `/me/`) | Custom scopes (`posts`, `media`, etc.) | +| **Use Cases** | “Login with WordPress.com” | WordPress.com site management | +| **Data Access** | Basic profile only | Blog posts, media, comments, etc. | + +**Important**: Do not use the same WordPress.com application for both Connect authentication and full API access. Connect tokens are limited to the `/me/` endpoint and cannot access blog content or management features. diff --git a/content/runtime/documentation/developer-tools/index.md b/content/runtime/documentation/developer-tools/index.md new file mode 100644 index 0000000..0d73f06 --- /dev/null +++ b/content/runtime/documentation/developer-tools/index.md @@ -0,0 +1,102 @@ +--- +type: document +title: Developer tools +description: "" +resource: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/developer-tools/" +tags: +timestamp: "2026-06-16T19:29:29+00:00" +wordpress: + id: 2514 + status: publish + type: documentation + author: 0 + date: "2026-06-16 19:29:29" + date_gmt: "2026-06-16 19:29:29" + modified: "2026-06-16 19:29:29" + modified_gmt: "2026-06-16 19:29:29" + slug: developer-tools + parent: 0 + menu_order: 0 + comment_status: closed + ping_status: closed + guid: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/developer-tools/" + comment_count: 0 +--- + +WordPress.com provides a powerful set of developer tools that make it easy to build and customize websites. These tools offer the flexibility and control needed to create robust, scalable sites. + +From local development with WordPress Studio to seamless GitHub deployments and access to the WordPress.com REST API, developers can streamline their workflows and deliver better user experiences. + +Whether you’re just getting started or have years of experience, WordPress.com’s developer tools are built to help you bring your ideas to life. You can learn more about each tool using the links below. + +## WordPress Studio + +WordPress Studio is a free desktop app that simplifies local WordPress development. It lets you quickly build and manage local sites, sync with live production or staging sites, and share your work using site previews hosted on WordPress.com. + +[Learn more](/docs/developer-tools/studio//) + +## Staging sites + +Staging sites allow you to clone your entire WordPress.com site. This is especially useful for troubleshooting issues, previewing major updates, or collaborating with others in a controlled environment. + +[Learn more](https://wordpress.com/support/how-to-create-a-staging-site/) + +## GitHub Deployments + +GitHub Deployments let you connect a GitHub repository to your WordPress.com site for reliable, automated code deployment. Changes pushed to the repo can be deployed to your site either automatically or on demand. + +[Learn more](https://wordpress.com/support/github-deployments/) + +## Bulk plugin management + +Use our intuitive Plugin Management tool to efficiently manage and update the plugins across all of your WordPress.com sites, all in one centralized dashboard. + +[Learn more](https://wordpress.com/support/plugins/update-plugins-in-bulk/) + +## Scheduled plugin updates + +Scheduled Plugin Updates let you choose exactly when your site checks for and installs plugin updates. This gives you full control over timing and helps minimize potential disruptions. + +[Learn more](https://wordpress.com/support/plugins/schedule-a-plugin-update/) + +## Block patterns + +Create beautiful posts, pages, and templates using WordPress.com patterns. Designed to match your theme’s global styles, these patterns work out of the box—no plugins or coding needed. Think of them as a component library for the block editor. + +[Learn more](/docs/developer-tools/block-patterns/) + +## WP-CLI + +WP-CLI is a command-line interface for WordPress that you can access when connected via SSH. This guide covers the most commonly used commands and their associated sub-commands. + +[Learn more](/docs/developer-tools/wp-cli/) + +## SFTP + +Secure File Transfer Protocol (SFTP) is a secure way to upload and download files between your computer and your WordPress.com site. It helps you manage your site’s files safely over an encrypted connection. + +[Learn more](https://wordpress.com/support/sftp/) + +## SSH + +SSH (Secure Shell) lets you access your site’s backend through a terminal app, allowing you to manage files and settings directly. It also gives you access to WP-CLI, a command-line tool for making changes and troubleshooting your site efficiently. + +[Learn more](https://wordpress.com/support/ssh/) + +## Database access + +You can use phpMyAdmin to access your website’s database and run a wide range of operations. This guide will show you how to administer your site’s MySQL database. + +[Learn more](https://wordpress.com/support/database/) + +## Web server settings + +In your website’s web server settings, you can configure options related to the PHP version and nonexistent assets on your site. This guide will explain each setting you can use to fine-tune how the web server runs your website. + +[Learn more](https://wordpress.com/support/hosting-configuration/) + +## REST API + +Explore the WordPress.com REST API to learn how you can interact with your site programmatically. You’ll find detailed documentation and a complete list of available endpoints to help you build powerful integrations and workflows. + +[Learn more](/docs/api/) diff --git a/content/runtime/documentation/developer-tools/server-cron-jobs.md b/content/runtime/documentation/developer-tools/server-cron-jobs.md new file mode 100644 index 0000000..fcaba2e --- /dev/null +++ b/content/runtime/documentation/developer-tools/server-cron-jobs.md @@ -0,0 +1,113 @@ +--- +type: document +title: Server Cron Jobs on WordPress.com +description: "" +resource: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/server-cron-jobs/" +tags: +timestamp: "2026-06-16T19:29:18+00:00" +wordpress: + id: 2432 + status: publish + type: documentation + author: 0 + date: "2026-06-16 19:29:18" + date_gmt: "2026-06-16 19:29:18" + modified: "2026-06-16 19:29:29" + modified_gmt: "2026-06-16 19:29:29" + slug: server-cron-jobs + parent: 2514 + menu_order: 0 + comment_status: closed + ping_status: closed + guid: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/server-cron-jobs/" + comment_count: 0 +--- + +Server Cron Jobs allow you to run scheduled commands directly on your site’s server. Unlike WP-Cron, server cron jobs do not depend on site traffic and run independently at regular intervals. + +This feature is available on sites with the Business plan or higher and is configured from the new Multi-site dashboard under the **Settings** tab: + +![The Cron setting in the WordPress.com Hosting Dashboard](https://developer.wordpress.com/wp-content/uploads/2026/02/server-cron-job-settings-wordpress-com.png)Under the **Cron** tab, you can add a command to run and see the list of scheduled jobs: + +![The Cron schedule page on WordPress.com](https://developer.wordpress.com/wp-content/uploads/2026/02/server-cron-job-schedule-wordpress-com.png)### What are Server Cron Jobs? + +A server cron job is a scheduled task that runs automatically at defined intervals. + +You can use server cron jobs for recurring maintenance or automation tasks. For example: + +- Clearing cache: `wp cache flush` +- Removing spam comments: `wp comment delete $(wp comment list --status=spam --format=ids)` + +These commands run in the server environment and are not affected by how much traffic your site receives. + +### Scheduling Server Cron Jobs + +You can schedule server cron jobs using one of the predefined options, or choose a custom schedule for more control: + +- Hourly +- Daily +- Twice daily +- Weekly +- Custom + +![](https://developer.wordpress.com/wp-content/uploads/2026/02/screenshot-2026-03-19-at-12.50.44.png)The Custom option lets you run a job multiple times per hour, per day, or per week. For example, you can schedule a job to run 2 times per hour, 3 times per day, or 2 times per week: + +[![](https://developer.wordpress.com/wp-content/uploads/2026/02/screenshot-2026-03-19-at-12.50.59.png?w=1024)](https://developer.wordpress.com/wp-content/uploads/2026/02/screenshot-2026-03-19-at-12.50.59.png)To help prevent system overload, the exact execution time is randomized within the selected interval. This applies to both predefined and custom schedules. For example, if you choose once per hour, the job may run at any point during that hour. + +### Command format and supported syntax + +Server Cron Jobs run the command you enter in a shell environment on your site’s server. + +- **WP-CLI commands** are supported (for example, commands starting with `wp`). +- **Shell features** such as output redirection (`>`, `>>`) and combining output/error (`2>&1`) are also supported. +- If you use shell features like pipes (`|`) or command substitution (`$(...)`), confirm the command works when run manually first. + +**Examples:** + +Run a WP-CLI command: + +`wp cache flush` + +Run a command that uses shell output redirection: + +`echo "Cron ran at $(date)" > /srv/htdocs/wp-content/cron-test.txt` + +Write both output and errors to a log file: + +`wp cache flush >> /srv/htdocs/wp-content/cron-debug.log 2>&1` + +**Note:** Traditional cron schedule expressions (for example, `*/5 * * * *`) are not currently supported in the scheduling UI. + +### Viewing command output and debugging + +There is currently no built-in execution log available in the dashboard. + +If you need to confirm that a command is running or view its output, you can use shell output redirection to write results to a file on your site. + +**Basic test** + +The following command creates a file in `wp-content` each time the cron job runs: + +`echo "Cron ran at $(date)" > /srv/htdocs/wp-content/cron-test.txt` + +If successful, `cron-test.tx` will appear in your `wp-content` directory. + +![A cron-test.txt file shown in a wp-content folder](https://developer.wordpress.com/wp-content/uploads/2026/02/cron-test-txt.png)You can access this [file using SFTP.](https://wordpress.com/support/sftp/) + +**Capturing output and errors** + +To record both standard output and errors to a log file, you can use: + +`command >> /srv/htdocs/wp-content/cron-debug.log 2>&1` + +Replace `command` with your actual command. For example: + +`mysqldump database >> /srv/htdocs/wp-content/cron-debug.log 2>&1` + +This appends all output to `cron-debug.log`, which you can download via SFTP for troubleshooting. + +## Relationship between WP-Cron and Server Cron Jobs + +[WP-Cron](https://developer.wordpress.com/docs/guides/wp-cron-on-wordpress-com/) continues to handle WordPress-level scheduled tasks such as publishing posts and running plugin background processes. + +Server Cron Jobs operate separately and run directly on the server. They are suitable for tasks that require consistent execution regardless of site traffic. diff --git a/content/runtime/documentation/developer-tools/site-accelerator-api.md b/content/runtime/documentation/developer-tools/site-accelerator-api.md new file mode 100644 index 0000000..90a9c16 --- /dev/null +++ b/content/runtime/documentation/developer-tools/site-accelerator-api.md @@ -0,0 +1,327 @@ +--- +type: document +title: Site Accelerator API +description: "" +resource: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/site-accelerator-api/" +tags: +timestamp: "2026-06-16T19:29:19+00:00" +wordpress: + id: 2438 + status: publish + type: documentation + author: 0 + date: "2026-06-16 19:29:19" + date_gmt: "2026-06-16 19:29:19" + modified: "2026-06-16 19:29:29" + modified_gmt: "2026-06-16 19:29:29" + slug: site-accelerator-api + parent: 2514 + menu_order: 0 + comment_status: closed + ping_status: closed + guid: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/site-accelerator-api/" + comment_count: 0 +--- + +[Site Accelerator from Jetpack](https://wordpress.com/support/site-accelerator-cdn/) is a Content Delivery Network (CDN) on WordPress.com, optimized to speed up your site by delivering faster images and static files. This guide explains how to use its API and available arguments. + +Site Accelerator CDN is automatically enabled on sites with the [WordPress.com Business and Commerce plans](https://wordpress.com/hosting/?ref=developer-docs#pricing-grid). + +## Query arguments + +You can crop, resize, and filter images served by the Site Accelerator CDN using the following GET query parameters. + +--- + +`GET?w=` + +Set the **w**idth of an image in pixels: + +`?w=300` + +![Image of the Fox Oakland Theater sign with a green traffic light in the foreground and a crowd of people walking down the street.](https://i0.wp.com/s.ma.tt/files/2012/06/DSC01205.jpg?w=300) + +--- + +`GET?h=` + +Set the **h**eight of an image in pixels: + +`?h=200` + +![Close-up of purple lavender flowers with a bee collecting nectar.](https://i0.wp.com/s.ma.tt/files/2012/06/MCM_0629-1600x1064.jpg?h=200) + +--- + +`GET?crop=x,y,w,h` + +Crop an image by percentages **x**-offset, **y**-offset, **w**idth, **h**eight (x,y,w,h). Percentages are used so that you don’t need to recalculate the cropping when transforming the image in other ways such as resizing it. + +For example, the following image takes a 60% by 60% rectangle from the [source image](http://s.ma.tt/files/2012/06/4-MCM_0830-1600x1064.jpg) starting at 12% offset from the left and 25% offset from the top. + +`?crop=12,25,60,60` + +![Close-up of glass containers with various colorful sauces or jams, displayed on a white tablecloth, with small spoons beside them.](https://i0.wp.com/s.ma.tt/files/2012/06/4-MCM_0830-1600x1064.jpg?crop=12,25,60,60)The next image takes a 788 by 788 square starting at 160 by 160. + +The next image takes a 788 by 788 square starting at 160 by 160. + +The next image takes a 788 by 788 square starting at 160 by 160. + +`?crop=160px,160px,788px,788px` + +You can also mix the parameters types, for example a 1400 pixels by 60% rectangle from the image starting at 160 pixels by 25%. + +You can also mix the parameters types, for example a 1400 pixels by 60% rectangle from the image starting at 160 pixels by 25%. + +You can also mix the parameters types, for example a 1400 pixels by 60% rectangle from the image starting at 160 pixels by 25%. + +`?crop=160px,25,1400px,60` + +![Close-up of three glass containers with domed lids, each holding different colored sauces or jams, placed on a white tablecloth.](https://i0.wp.com/s.ma.tt/files/2012/06/4-MCM_0830-1600x1064.jpg?crop=160px,160px,788px,788px)![A row of small glass jars containing colorful sauces or condiments, each topped with a glass lid, placed on a white tablecloth with silver spoons beside them.](https://i0.wp.com/s.ma.tt/files/2012/06/4-MCM_0830-1600x1064.jpg?crop=160px,25,1400px,60) + +--- + +`GET?resize=` + +Resize and crop an image to the exact **w**idth,**h**eight pixel dimensions. Set the first number as close to the target size as possible and then crop the rest. Which direction it’s resized and cropped depends on the aspect ratios of the original image and the target size. + +`?resize=400,220` + +![Scenic view of a coastal landscape with hills, a winding road, and a clear blue sky.](https://i0.wp.com/s.ma.tt/files/2012/06/9-DSC01406-1600x1066.jpg?resize=400,220)`?resize=200,400` + +![A tabby cat resting its front paws on a balcony railing, with a blurred background of greenery.](https://i0.wp.com/s.ma.tt/files/2010/11/MCM_4443.jpg?resize=200,400)This is useful for taking an image of any size and making it fit into a certain location while losing as little of the image as possible. + +This is useful for taking an image of any size and making it fit into a certain location while losing as little of the image as possible. + +This is useful for taking an image of any size and making it fit into a certain location while losing as little of the image as possible. + +--- + +`GET?fit=` + +Fit an image to a containing box of **w**idth, **h**eight dimensions. Image aspect ratio is maintained. + +``?fit=300,300`` + +![A reflective metallic sphere sculpture on a wet surface, capturing the surrounding cityscape and trees.](https://i0.wp.com/s.ma.tt/files/2010/10/MCM_4049.jpg?fit=300,300) + +``?fit=300,300`` + +![A bottle of Jameson Distillery Reserve 12 whiskey displayed next to a glass of red wine on a dining table.](https://i0.wp.com/s.ma.tt/files/2010/10/MCM_4214.jpg?fit=300,300) + +For example, `fit=100,100` on a landscape image with dimensions 400×300 will result in an image that is 100×75, while `fit=100,100` on a portrait image with dimensions 300×400 will result in an image that is 75×100. + +For example, `fit=100,100` on a landscape image with dimensions 400×300 will result in an image that is 100×75, while `fit=100,100` on a portrait image with dimensions 300×400 will result in an image that is 75×100. + +For example, `fit=100,100` on a landscape image with dimensions 400×300 will result in an image that is 100×75, while `fit=100,100` on a portrait image with dimensions 300×400 will result in an image that is 75×100. + +--- + +`GET?lb=` + +Add black letterboxing effect to images, by scaling them to **w**idth, **h**eight while maintaining the aspect ratio and filling the rest with black. + +**Original Image** + +![A scenic view of a calm sea with rocky shores under a cloudy sky, showcasing a distant coastline with mountains.](https://i0.wp.com/developer.files.wordpress.com/2013/03/letterboxing-example.jpg) + +`?lb=310,250` + +![Scenic view of a rocky coastline with waves crashing against the rocks, under a cloudy sky, with distant mountains and a coastal town in the background.](https://i0.wp.com/developer.files.wordpress.com/2013/03/letterboxing-example.jpg?lb=310,250) + +--- + +`GET?ulb=` + +Remove black letterboxing effect from images with **ulb**. This function takes only one argument, `true`. + +**Original Image** + +![Black and white image of two men in a crowd, one wearing a cap with 'RIP G' and the other looking on.](https://i0.wp.com/developer.files.wordpress.com/2012/11/black-letterboxing-example.jpg) + +`?ulb=true` + +![Black and white image of two individuals in a lively atmosphere, one wearing a cap with 'RIP' printed on it and smiling, while the other appears contemplative.](https://i0.wp.com/developer.files.wordpress.com/2012/11/black-letterboxing-example.jpg?ulb=true) + +--- + +`GET?filter=` + +The **filter** parameter is used to apply one of multiple filters. Valid values are: `negate`, `grayscale`, `sepia`, `edgedetect`, `emboss`, `blurgaussian`, `blurselective`, `meanremoval`. + +**Original Image** + +![A cup of tea with a teabag on a saucer, accompanied by a piece of pastry and a teapot in the background.](https://i0.wp.com/s.ma.tt/files/2010/12/MCM_5875-1600x1064.jpg?w=200) + +`?filter=negate` + +![An inverted image of a cup with a tea bag on a saucer, accompanied by a blue pastry and a teapot.](https://i0.wp.com/s.ma.tt/files/2010/12/MCM_5875-1600x1064.jpg?w=200&filter=negate) + +`?filter=grayscale` + +![A black and white image of a coffee cup with a tea bag tag, a piece of bread, and a teapot in the background, placed on a wooden surface.](https://i0.wp.com/s.ma.tt/files/2010/12/MCM_5875-1600x1064.jpg?w=200&filter=grayscale) + +`?filter=sepia` + +![A cup of coffee with a tea bag on the saucer, accompanied by a biscuit and a teapot in the background.](https://i0.wp.com/s.ma.tt/files/2010/12/MCM_5875-1600x1064.jpg?w=200&filter=sepia) + +`?filter=edgedetect` + +![A cup of coffee on a saucer with a biscuit, accompanied by a teapot, featuring a label on the cup.](https://i0.wp.com/s.ma.tt/files/2010/12/MCM_5875-1600x1064.jpg?w=200&filter=edgedetect) + +`?filter=emboss` + +![Cup of coffee with a pastry on a plate, a sugar packet in the cup, and a teapot in the background, artistically filtered.](https://i0.wp.com/s.ma.tt/files/2010/12/MCM_5875-1600x1064.jpg?w=200&filter=emboss) + +`?filter=blurgaussian` + +![A cup of tea with a teabag tag, accompanied by a teapot and a piece of bread on a saucer, placed on a wooden table.](https://i0.wp.com/s.ma.tt/files/2010/12/MCM_5875-1600x1064.jpg?w=200&filter=blurgaussian) + +`?filter=blurselective` + +![A cup of coffee with a logo sticker on it, accompanied by a small plate with a pastry, a teapot, and a sugar packet, all placed on a wooden table.](https://i0.wp.com/s.ma.tt/files/2010/12/MCM_5875-1600x1064.jpg?w=200&filter=blurselective) + +`?filter=meanremoval` + +![A cup of tea with a teabag resting on the rim, accompanied by a pastry on a plate, set on a wooden table.](https://i0.wp.com/s.ma.tt/files/2010/12/MCM_5875-1600x1064.jpg?w=200&filter=meanremoval) + +--- + +`GET?brightness=` + +Adjust the **brightness** of an image. Valid values are -255 through 255 where -255 is black and 255 is white. Higher is brighter. The default is zero. + +`?brightness=-40` + +![A bird in flight against a gray sky.](https://i0.wp.com/s.ma.tt/files/2011/06/MCM_9517-1600x1065.jpg?brightness=-40) + +`?brightness=0` + +![A bird flying against a cloudy gray sky.](https://i0.wp.com/s.ma.tt/files/2011/06/MCM_9517-1600x1065.jpg?brightness=0) + +`?brightness=80` + +![A white bird in flight against a bright white background.](https://i0.wp.com/s.ma.tt/files/2011/06/MCM_9517-1600x1065.jpg?brightness=80) + +--- + +`GET?contrast=` + +Adjust the **contrast** contrast of an image. Valid values are -100 through 100. The default is zero. + +`?contrast=-50` + +![A bird flying against a cloudy sky.](https://i0.wp.com/s.ma.tt/files/2011/06/MCM_9517-1600x1065.jpg?contrast=-50) + +`?contrast=0` + +![A bird in flight against a gray sky.](https://i0.wp.com/s.ma.tt/files/2011/06/MCM_9517-1600x1065.jpg?contrast=0) + +`?contrast=50` + +![A bird in flight against a white background.](https://i0.wp.com/s.ma.tt/files/2011/06/MCM_9517-1600x1065.jpg?contrast=50) + +--- + +`GET?colorize=` + +Add color hues to an image with **colorize** by passing a comma separated list of red, green, and blue (RGB). For example, values such as 255,0,0 (red), 0,255,0 (green), 0,0,255 (blue). + +`?colorize=100,0,0` + +![](https://i0.wp.com/s.ma.tt/files/2024/02/IMG_3775.jpeg?colorize=100,0,0) + +`?colorize=0,100,0` + +![](https://i0.wp.com/s.ma.tt/files/2024/02/IMG_3775.jpeg?colorize=0,100,0) + +`?colorize=0,0,100` + +![A lighthouse standing on a rocky cliff with greenery surrounding it and a blue sky in the background.](https://i0.wp.com/s.ma.tt/files/2024/02/IMG_3775.jpeg?colorize=0,0,100) + +--- + +`GET?smooth=` + +The **smooth** parameter can be used to smooth out the image. + +**Original image** + +![Close-up view of a vintage aircraft engine and propeller with orange and white color scheme, showcasing the engine components and a glimpse of the landscape in the reflection.](https://i0.wp.com/s.ma.tt/files/2011/06/MCM_9230-1600x1064.jpg) + +`?smooth=1` + +![Close-up view of an orange and white vintage airplane with a propeller, set against a clear blue sky.](https://i0.wp.com/s.ma.tt/files/2011/06/MCM_9230-1600x1064.jpg?w=310&smooth=1) + +According to the PHP manual, the function applies a 9-cell convolution matrix where the center pixel is weighted by the value of the first argument, and all surrounding pixels have a weight of 1. The result is normalized by dividing by the total weight. In simpler terms, a value of 0 results in maximum smoothing, while higher values reduce the smoothing effect. Values around 2048 or more have little to no visible impact. + +--- + +`GET?zoom=` + +Use **zoom** to size images for high pixel ratio devices and browsers when zoomed. Not available to use with crop. Zoom is intended for use by scripts such as devicepx.js which automatically set the zoom level. Valid zoom levels are 1, 1.5, 2-10. + +**Original image** + +![A child holding a stick with smoke rising, in front of a crowd during a celebration outdoors, with mountains in the background.](https://i0.wp.com/s.ma.tt/files/2012/02/MCM_4246-1600x1064.jpg?w=310) + +`?zoom=2` + +![A young girl dressed in a blue dress holds a tall bundle of burning sticks while an Ethiopian flag flutters in the background. The scene is set in a rural area with a group of spectators in the background.](https://i0.wp.com/s.ma.tt/files/2012/02/MCM_4246-1600x1064.jpg?zoom=2) + +--- + +`GET?quality=` + +Use this parameter to manage the quality output of the images. Valid settings are between the values 10 and 100. The degree of compression depends on the image, its lossy or lossless nature, and the requesting web browser’s capabilities. + +For lossless images, providing the quality input less than 100 will result in a lossy image provided the requested browser supports this image type. Below is an example that shows conversion of a non-transparent PNG (lossless) image to a JPEG (or lossy WebP if browser supports it) when quality is specified. + +If the quality is not specified, photon will try to preserve the original quality. + +**Original image** + +![Close-up image of two black ants interacting on a piece of wood with a blurred green background.](https://i0.wp.com/ma.tt/files/2014/09/8084136238_169f1ca1f0_o.jpg?w=310) + +`?quality=50` + +![Close-up of two ants engaged in a confrontation on a wooden surface, with a blurred natural background.](https://i0.wp.com/ma.tt/files/2014/09/8084136238_169f1ca1f0_o.jpg?w=310&quality=50) + +**Original png image** + +![Original png (lossless) image](https://i0.wp.com/ma.tt/files/2025/06/image-1.png) + +?`quality=60` + +![Original image is now converted to jpeg (lossy) because `?quality=60` attribute is specified](https://i0.wp.com/ma.tt/files/2025/06/image-1.png?quality=60) + +`GET?allow_lossy=` + +Use this parameter to control whether the Image CDN may serve a lossy-compressed version of an image. When `allow_lossy=1` is specified, the CDN will attempt to deliver a lossy format (for example, JPEG or WebP) if the requesting browser supports it. + +Below is an example that demonstrates how a non-transparent PNG (lossless) image can be converted to a JPEG (or lossy WebP if browser supports it) when `allow_lossy=1` is included in the request. + +**Original png image** + +![Original png (lossless) image](https://i0.wp.com/ma.tt/files/2025/06/image-1.png) + +?`allow_lossy=1` + +![Original image is now converted to jpeg (lossy) because `?allow_lossy=1` attribute is specified](https://i0.wp.com/ma.tt/files/2025/06/image-1.png?allow_lossy=1) + +--- + +`GET?strip=` + +Use the **strip** functionality to control how metadata is preserved. Color profiles are always applied and removed, but other metadata may be kept. All data is stripped by default, with any existing orientation data being first applied to the image. There are 2 valid settings for this parameter: + +- **all**: strips all extraneous data (this is the default). +- **none**: preserves Exif, IPTC and XMP. + +**Original image** + +![Close-up of yellow flowers with a green background.](https://i0.wp.com/ma.tt/files/2012/06/13-MCM_0885.jpg?w=310) + +`?strip=none` + +![Close-up of vibrant yellow flowers amidst green foliage, taken from above.](https://i0.wp.com/ma.tt/files/2012/06/13-MCM_0885.jpg?w=310&strip=all) diff --git a/content/runtime/documentation/developer-tools/studio/agent-skills-wordpress-studio.md b/content/runtime/documentation/developer-tools/studio/agent-skills-wordpress-studio.md new file mode 100644 index 0000000..115e5d8 --- /dev/null +++ b/content/runtime/documentation/developer-tools/studio/agent-skills-wordpress-studio.md @@ -0,0 +1,74 @@ +--- +type: document +title: Agent Skills in WordPress Studio +description: "" +resource: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/agent-skills-wordpress-studio/" +tags: +timestamp: "2026-06-16T19:29:17+00:00" +wordpress: + id: 2426 + status: publish + type: documentation + author: 0 + date: "2026-06-16 19:29:17" + date_gmt: "2026-06-16 19:29:17" + modified: "2026-06-16 19:29:29" + modified_gmt: "2026-06-16 19:29:29" + slug: agent-skills-wordpress-studio + parent: 2481 + menu_order: 0 + comment_status: closed + ping_status: closed + guid: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/agent-skills-wordpress-studio/" + comment_count: 0 +--- + +Agent Skills give your AI coding agent specialized knowledge about WordPress development. Studio bundles a set of skills you can install into your sites so agents like Claude Code or Cursor pick them up automatically. + +## What are Agent Skills? + +An Agent Skill is a `SKILL.md` file that tells the agent how to approach a specific area of WordPress development. When a skill is installed in a site, the agent reads it and applies the guidance it contains before starting work. + +You can use skills to help agents handle tasks like: + +- Building a custom block with the correct `block.json` structure +- Creating a plugin that follows WordPress coding standards and security practices +- Working with REST API routes and authentication + +## Available skills in Studio + +Studio ships with the following built-in skills: + +- **Studio CLI**: WordPress development workflows using Studio CLI +- **Plugin Development**: Hooks, settings API, security, and packaging +- **Block Development**: `Block.json`, attributes, rendering, and deprecations +- **Block Themes**: Theme.json, templates, patterns, and style variations +- **REST API** — Routes, endpoints, schema, and authentication +- **WP-CLI & Ops** — CLI commands, automation, and search-replace + +## Where skills are stored + +When a skill is installed, Studio copies it into the site directory: + +![Folder structure of a web development project showing directories and files related to WordPress, including 'wp-config.php' and various folders like 'skills' and 'studio-cli'.](https://developer.wordpress.com/wp-content/uploads/2026/04/image-6.png?w=624)For agents that use Claude’s directory layout, Studio also creates a symlink at `.claude/skills/` pointing to the same location. No additional configuration is needed for Claude Code to pick up the skill. + +## Installing and removing skills in Studio + +There are two ways to manage skills in Studio – globally and per site. + +You can find the global settings for skills under *Settings → Skills* modal: + +![Settings menu for managing WordPress site skills, showing installed options like Studio CLI, Plugin Development, Block Development, and REST API, along with available skills.](https://developer.wordpress.com/wp-content/uploads/2026/04/screenshot-2026-04-21-at-14.49.53.png?w=1024)From that screen you can: + +- Click *Install* next to an individual skill + +![Interface for plugin development options including a brief description and install buttons.](https://developer.wordpress.com/wp-content/uploads/2026/04/image-5.png)- Click Install all to install every available skill at once +- Open the toggle menu next to an installed skill and select *Remove* to uninstall it + +![Screenshot of a user interface showing installed WordPress tools, including 'Studio CLI' and 'Block Development', with a 'Remove' button highlighted.](https://developer.wordpress.com/wp-content/uploads/2026/04/image-7.png)Installing or removing a skill applies to all existing sites immediately. Any new site you create will also receive the currently installed skills automatically. + +## Managing skills per site + +The per-site modal reflects the actual state of the `.agents/skills/` directory on disk for a specific site. You can use it to manage skills for a specific site without changing the global selection. + +You can access the per site skills selection from the **Overview** tab in the **Edit site** modal. diff --git a/content/runtime/documentation/developer-tools/studio/assistant.md b/content/runtime/documentation/developer-tools/studio/assistant.md new file mode 100644 index 0000000..e4d4537 --- /dev/null +++ b/content/runtime/documentation/developer-tools/studio/assistant.md @@ -0,0 +1,74 @@ +--- +type: document +title: Studio Assistant +description: "" +resource: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/assistant/" +tags: +timestamp: "2026-06-16T19:29:24+00:00" +wordpress: + id: 2477 + status: publish + type: documentation + author: 0 + date: "2026-06-16 19:29:24" + date_gmt: "2026-06-16 19:29:24" + modified: "2026-06-16 19:29:30" + modified_gmt: "2026-06-16 19:29:30" + slug: assistant + parent: 2481 + menu_order: 0 + comment_status: closed + ping_status: closed + guid: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/assistant/" + comment_count: 0 +--- + +[Studio Code](https://developer.wordpress.com/docs/developer-tools/studio/studio-code/) is recommended for taking full advantage of AI when building WordPress sites with Studio. + +The Studio Assistant is a smart chatbot integrated within [WordPress Studio](https://developer.wordpress.com/studio/), our free and open source local development app. With the Studio Assistant, you can quickly configure new sites, manage existing sites, and run complex WP-CLI commands—all through a simple and intuitive chat interface. + +## How to use the Studio Assistant + +To access the Studio Assistant, open your WordPress Studio app and click on the Assistant tab. + +[![A screenshot of the Studio app with an orange arrows pointing to Studio Assistant tab.](https://developer.wordpress.com/wp-content/uploads/2024/10/studio-assistant-2.jpg)](https://developer.wordpress.com/wp-content/uploads/2024/10/studio-assistant-2.jpg)Each Studio site will have its own unique chat conversation, allowing the assistant to understand and respond based on the specific context of your site. + +To access the Assistant, you must be [logged into your WordPress.com account](https://developer.wordpress.com/docs/developer-tools/studio/#connect-wordpress-com), as we use WordPress.com infrastructure to generate responses and manage access. Each user is allowed 200 prompts per month across all of their Studio sites. + +## Notable features + +You can use the Assistant to streamline workflows for your local sites like: + +### Performing actions based on your site specs + +The Studio Assistant has context about your site (like the themes and plugins that are installed), so it can tailor its responses based on your specific site features. + +For example, you can ask the Assistant to disable or update the plugins that are already installed on your local site or to upgrade your site’s WordPress version, even for beta or RC versions. + +### WP-CLI suggestions and execution + +You don’t need to install WP-CLI on your computer to run WP-CLI commands with the Studio Assistant. When the Assistant recommends running a WP-CLI command, you will be able to run the command inline within the Assistant interface by clicking the **Run** button. + +![A screenshot of the Studio Assistant with an orange arrows pointing to the Run button.](https://developer.wordpress.com/wp-content/uploads/2024/10/studio-assistant-run-1.jpg)[If you’ve already installed WP-CLI](https://make.wordpress.org/cli/handbook/guides/installing/), you can click the **Open in terminal** button to copy the command and then run it in your terminal. This is especially useful when you need to modify some parameters. + +A few WP-CLI commands, such as `db`, `server`, and `shell`, are not currently compatible with the execution inline, and the buttons to run these commands won’t be visible in the Studio Assistant. + +If you want to use WP-CLI outside of the Studio Assistant, you must have WP-CLI on your machine. We recommend [following these instructions](https://make.wordpress.org/cli/handbook/guides/installing/) if you don’t already have it installed. + +### Generate code and content + +When you ask the Assistant to write posts, it will provide you with Gutenberg blocks that you can simply copy and paste into your wp-admin editor. + +For creating PHP, JavaScript, or CSS code, the Assistant will also generate code blocks that you can copy, paste, and adapt to your specific needs. + +All code blocks include a convenient copy button to easily copy their content. + +![A screenshot of the Studio Assistant with an orange arrows pointing to the copy button.](https://developer.wordpress.com/wp-content/uploads/2024/10/studio-assistant-copy-1.jpg)### Open files + +If you have a file in mind but don’t want to look for it in your Finder, File Explorer, or text editor, simply ask the Assistant to open it for you. In the Assistant’s response, you can click on the file name to open files with your IDE or folders in your file explorer. + +![A screenshot of the Studio Assistant with orange arrows pointing to the links that open files.](https://developer.wordpress.com/wp-content/uploads/2024/10/studio-assistant-open-files.jpg)### Clear the conversation + +Any time you want to start a new conversation for a given site, you can clear the current conversation by clicking on the three dots menu and clicking the **Clear conversation** button. + +![A screenshot of the Studio Assistant with an orange arrows pointing to the button that clears the conversation.](https://developer.wordpress.com/wp-content/uploads/2024/10/studio-assistant-clear.jpg) diff --git a/content/runtime/documentation/developer-tools/studio/blueprints/index.md b/content/runtime/documentation/developer-tools/studio/blueprints/index.md new file mode 100644 index 0000000..c8d4735 --- /dev/null +++ b/content/runtime/documentation/developer-tools/studio/blueprints/index.md @@ -0,0 +1,79 @@ +--- +type: document +title: Blueprints in WordPress Studio +description: "" +resource: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/blueprints/" +tags: +timestamp: "2026-06-16T19:29:19+00:00" +wordpress: + id: 2440 + status: publish + type: documentation + author: 0 + date: "2026-06-16 19:29:19" + date_gmt: "2026-06-16 19:29:19" + modified: "2026-06-16 19:29:29" + modified_gmt: "2026-06-16 19:29:29" + slug: blueprints + parent: 2481 + menu_order: 0 + comment_status: closed + ping_status: closed + guid: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/blueprints/" + comment_count: 0 +--- + +A Blueprint is a JSON file that describes how to build a site in WordPress Studio. This “recipe” tells Studio which WordPress and PHP versions to use, which plugins and themes to install, what content or settings to apply, and more. + +Unlike full-site Blueprints in other local development environments, Studio Blueprints are lightweight, declarative, and easy to share. Choose from one of our free starter Blueprints or upload a [Blueprint of your own](https://developer.wordpress.com/docs/guides/how-to-create-custom-blueprints/). + +## How Blueprints work in Studio + +When you launch a site with a Blueprint, Studio reads the JSON file and builds the site according to the instructions inside. Instead of copying a pre-existing site, Studio installs and configures everything fresh each time. This ensures that anyone using the same Blueprint ends up with the same environment. + +A Blueprint can configure: + +- **Core versions**: Specify which WordPress and PHP versions the site should use. +- **Plugins and themes**: Define which should be installed and activated automatically. +- **Site options**: Set values such as the site title, permalink structure, and other WordPress settings. +- **Content**: Import demo posts, pages, or other starter content. +- **Custom steps**: Run PHP or SQL commands during site creation to further customize the setup. + +Blueprints in Studio follow the same format as [WordPress Playground](https://wordpress.org/playground/) Blueprints. That means a Blueprint you create for Studio can also be opened in Playground (and vice versa), making them portable across different development contexts. + +Studio does not support *every* Playground feature. Unsupported steps are skipped without affecting the rest of the Blueprint. For a comprehensive list of these steps, refer to the [Blueprints guide](https://developer.wordpress.com/docs/guides/how-to-create-custom-blueprints/#1-blueprint-limitations-in-studio). + +## Creating a Studio site from a Blueprint + +Creating local sites from Blueprints is incorporated into the site creation flow within Studio. + +1. Click the “**Add site**” button in the lower left corner of the Studio app. The following screen will appear. + +[![The new "Add a site" screen in WordPress Studio.](https://developer.wordpress.com/wp-content/uploads/2025/10/new-studio-site.png?w=1024)](https://developer.wordpress.com/wp-content/uploads/2025/10/new-studio-site.png)1. Select “**Build a new site,**” and you will see a gallery of featured Blueprints and an option to choose your own custom Blueprint file. + +[![The new "Build a new site" screen in WordPress Studio showcases the Featured Blueprints as well as the option to upload your own.](https://developer.wordpress.com/wp-content/uploads/2025/10/build-new-site.png?w=1024)](https://developer.wordpress.com/wp-content/uploads/2025/10/build-new-site.png)1. Select a featured Blueprint that fits your needs or “**Choose blueprint file**” and select the JSON file from your computer. +2. Click **Continue**. +3. On the setup screen, give your site a name. You can open “**Advanced settings**” for more options. +4. Click “**Add site.**“ + +![Set the site name and configure advanced settings.](https://developer.wordpress.com/wp-content/uploads/2025/10/studio-add-site-name-settings-16-1.jpg)Behind the scenes, Studio builds the site from whichever Blueprint you selected or added. + +## Featured Blueprints + +Studio currently has three free featured Blueprints that you can use when setting up a new local site. + +1. **Quick Start**: A WordPress.com-like environment that mirrors the Business plan. It includes the same core plugins and themes you’d find pre-installed on a WordPress.com Business plan, so you can spin up a production-like site right away. +2. **Development**: Designed for building themes and plugins, this Blueprint enables debug settings and includes tools like Query Monitor, Plugin Check, Theme Check, and Create Block Theme. +3. **Commerce**: Tailored for launching an online store, this Blueprint comes with WooCommerce and companion plugins pre-installed, along with optional extensions such as payment, advertising, and product listing tools. It provides a store-ready framework that you can extend for client projects. + +Additionally, Studio offers access to the Blueprints Gallery, where you can browse and activate a growing library of pre-configured environments tailored for things like blogging, ecommerce, development, design exploration, or plugin testing. + +[![The image shows Blueprints Gallery: a selection of blueprints that can be activated.](https://developer.wordpress.com/wp-content/uploads/2025/10/blueprints-gallery.png?w=1024)](https://developer.wordpress.com/wp-content/uploads/2025/10/blueprints-gallery.png)## Building your own Blueprints + +Beyond the featured Blueprints, you can also create a custom JSON file to define your specific site requirements. For details on supported steps, JSON structure, and examples, refer to [How to create custom Blueprints](https://developer.wordpress.com/docs/guides/how-to-create-custom-blueprints/). + +## Opening Blueprints in Studio + +You can use a custom Blueprint when creating a new site in Studio, but you can also generate shareable links that open your Blueprint directly in the app (as long as the user has Studio installed). This makes it easy to share demos and examples that others can explore locally. Use the button below to learn how to create your own links. + +Open in WordPress Studio button diff --git a/content/runtime/documentation/developer-tools/studio/blueprints/open-in-wordpress-studio-button.md b/content/runtime/documentation/developer-tools/studio/blueprints/open-in-wordpress-studio-button.md new file mode 100644 index 0000000..f632af2 --- /dev/null +++ b/content/runtime/documentation/developer-tools/studio/blueprints/open-in-wordpress-studio-button.md @@ -0,0 +1,40 @@ +--- +type: document +title: Open in WordPress Studio button +description: "" +resource: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/open-in-wordpress-studio-button/" +tags: +timestamp: "2026-06-16T19:29:18+00:00" +wordpress: + id: 2436 + status: publish + type: documentation + author: 0 + date: "2026-06-16 19:29:18" + date_gmt: "2026-06-16 19:29:18" + modified: "2026-06-16 19:29:29" + modified_gmt: "2026-06-16 19:29:29" + slug: open-in-wordpress-studio-button + parent: 2440 + menu_order: 0 + comment_status: closed + ping_status: closed + guid: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/open-in-wordpress-studio-button/" + comment_count: 0 +--- + +The Open in WordPress Studio button lets users spin up a new WordPress Studio site from a [Blueprint](https://developer.wordpress.com/docs/developer-tools/studio/blueprints/) with a single click. When someone clicks the button or link, Studio launches on their machine (if installed) and creates a new site based on the Blueprint you provide. If they don’t have Studio installed, they’re sent to [the Studio landing page](https://developer.wordpress.com/studio/) to download the app. Once installed, click the button again to launch the site. + +You can embed Open in WordPress Studio buttons and links anywhere you share your work: GitHub repositories, plugin or theme listings, documentation, YouTube descriptions, and more. It’s a quick way to help users start working in Studio with your recommended setup. + +Here’s an example that creates a new site in Studio with a Blueprint built for WordPress plugin and theme development. + +[Open in WordPress Studio](https://wp.com/open?deep_link=add-site%3Fblueprint%3DewogICJsb2dpbiI6IHRydWUsCiAgInBsdWdpbnMiOiBbCiAgICAiZ3V0ZW5iZXJnIgogIF0sCiAgInByZWZlcnJlZFZlcnNpb25zIjogewogICAgInBocCI6ICI4LjMiLAogICAgIndwIjogImxhdGVzdCIKICB9LAogICJzdGVwcyI6IFsKICAgIHsKICAgICAgInN0ZXAiOiAiZGVmaW5lV3BDb25maWdDb25zdHMiLAogICAgICAiY29uc3RzIjogewogICAgICAgICJXUF9ERUJVRyI6IHRydWUsCiAgICAgICAgIldQX0RFQlVHX0RJU1BMQVkiOiBmYWxzZSwKICAgICAgICAiV1BfREVCVUdfTE9HIjogdHJ1ZSwKICAgICAgICAiV1BfREVWRUxPUE1FTlRfTU9ERSI6IHRydWUKICAgICAgfSwKICAgICAgIm1ldGhvZCI6ICJyZXdyaXRlLXdwLWNvbmZpZyIKICAgIH0sCiAgICB7CiAgICAgICJzdGVwIjogImluc3RhbGxQbHVnaW4iLAogICAgICAicGx1Z2luRGF0YSI6IHsKICAgICAgICAicmVzb3VyY2UiOiAid29yZHByZXNzLm9yZy9wbHVnaW5zIiwKICAgICAgICAic2x1ZyI6ICJjcmVhdGUtYmxvY2stdGhlbWUiCiAgICAgIH0sCiAgICAgICJvcHRpb25zIjogewogICAgICAgICJhY3RpdmF0ZSI6IGZhbHNlCiAgICAgIH0KICAgIH0sCiAgICB7CiAgICAgICJzdGVwIjogImluc3RhbGxQbHVnaW4iLAogICAgICAicGx1Z2luRGF0YSI6IHsKICAgICAgICAicmVzb3VyY2UiOiAid29yZHByZXNzLm9yZy9wbHVnaW5zIiwKICAgICAgICAic2x1ZyI6ICJwbHVnaW4tY2hlY2siCiAgICAgIH0sCiAgICAgICJvcHRpb25zIjogewogICAgICAgICJhY3RpdmF0ZSI6IGZhbHNlCiAgICAgIH0KICAgIH0sCiAgICB7CiAgICAgICJzdGVwIjogImluc3RhbGxQbHVnaW4iLAogICAgICAicGx1Z2luRGF0YSI6IHsKICAgICAgICAicmVzb3VyY2UiOiAid29yZHByZXNzLm9yZy9wbHVnaW5zIiwKICAgICAgICAic2x1ZyI6ICJxdWVyeS1tb25pdG9yIgogICAgICB9LAogICAgICAib3B0aW9ucyI6IHsKICAgICAgICAiYWN0aXZhdGUiOiBmYWxzZQogICAgICB9CiAgICB9LAogICAgewogICAgICAic3RlcCI6ICJpbnN0YWxsUGx1Z2luIiwKICAgICAgInBsdWdpbkRhdGEiOiB7CiAgICAgICAgInJlc291cmNlIjogIndvcmRwcmVzcy5vcmcvcGx1Z2lucyIsCiAgICAgICAgInNsdWciOiAidGhlbWUtY2hlY2siCiAgICAgIH0sCiAgICAgICJvcHRpb25zIjogewogICAgICAgICJhY3RpdmF0ZSI6IGZhbHNlCiAgICAgIH0KICAgIH0sCiAgICB7CiAgICAgICJzdGVwIjogInJ1blBIUCIsCiAgICAgICJjb2RlIjogIjw%252FcGhwIHJlcXVpcmVfb25jZSAnL3dvcmRwcmVzcy93cC1sb2FkLnBocCc7ICR3cF9yZXdyaXRlLT5zZXRfcGVybWFsaW5rX3N0cnVjdHVyZSggJy8lcG9zdG5hbWUlLycgKTsgaW5jbHVkZV9vbmNlKCBBQlNQQVRIIC4gJ3dwLWFkbWluL2luY2x1ZGVzL3BsdWdpbi5waHAnICk7IGRlYWN0aXZhdGVfcGx1Z2lucyggJ2hlbGxvLnBocCcsICdoZWxsby1kb2xseScsICdha2lzbWV0L2FraXNtZXQucGhwJyApOyBpbmNsdWRlX29uY2UoIEFCU1BBVEggLiAnd3AtYWRtaW4vaW5jbHVkZXMvZmlsZS5waHAnICk7IGRlbGV0ZV9wbHVnaW5zKCBbICdoZWxsby5waHAnLCAnaGVsbG8tZG9sbHknLCAnYWtpc21ldC9ha2lzbWV0LnBocCcgXSApOyIKICAgIH0sCiAgICB7CiAgICAgICJzdGVwIjogInVwZGF0ZVVzZXJNZXRhIiwKICAgICAgIm1ldGEiOiB7CiAgICAgICAgImFkbWluX2NvbG9yIjogIm1vZGVybiIsCiAgICAgICAgInNob3dfd2VsY29tZV9wYW5lbCI6IDAKICAgICAgfSwKICAgICAgInVzZXJJZCI6IDEKICAgIH0KICBdCn0%253D) + +## Generate your own + +Use this tool to build your own Open in WordPress Studio button or link. Paste any publicly accessible Blueprint URL, Base64 encoded JSON, or raw JSON, and an embed code will be generated. If you haven’t created a Blueprint before, see the [Blueprint guide](https://developer.wordpress.com/docs/guides/how-to-create-custom-blueprints/) for how to create one. + + Blueprint + + Markdown HTML URL `` Copy diff --git a/content/runtime/documentation/developer-tools/studio/changelog.md b/content/runtime/documentation/developer-tools/studio/changelog.md new file mode 100644 index 0000000..a117e6f --- /dev/null +++ b/content/runtime/documentation/developer-tools/studio/changelog.md @@ -0,0 +1,762 @@ +--- +type: document +title: WordPress Studio Changelog +description: "" +resource: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/changelog/" +tags: +timestamp: "2026-06-16T19:29:21+00:00" +wordpress: + id: 2446 + status: publish + type: documentation + author: 0 + date: "2026-06-16 19:29:21" + date_gmt: "2026-06-16 19:29:21" + modified: "2026-06-16 19:29:29" + modified_gmt: "2026-06-16 19:29:29" + slug: changelog + parent: 2481 + menu_order: 0 + comment_status: closed + ping_status: closed + guid: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/changelog/" + comment_count: 0 +--- + +WordPress Studio ships fast and often. This changelog highlights what’s new, what’s improved, and what’s been fixed in each release. While you can always [view technical release notes on GitHub](https://github.com/Automattic/studio/releases), this page gives you the bigger picture: how each update helps you build faster, safer, and smarter with WordPress. + +## 1.11.0 + +- Made Studio Code the default in the Studio app, replacing the previous Studio Assistant tab +- Improved site status check for JSON format +- Improved context for errors that bubble up from wordpress-server-child +- Fixed multiple issues with the Dark theme for Studio Code +- Fixed CLI symlink updates after Studio app update +- Adjusted error display when backup status response is unexpected +- Improved onboarding ToS/Privacy notices above the login CTA +- Added one-time ToS/Privacy disclaimer in Studio CLI and Studio Code +- Updated multiple dependencies, including WordPress packages and React + +## 1.10.0 + +- Released remote-session as beta-feature +- Added native PHP runtime support as a beta-feature to improve performance +- Added CLI support for the Blueprints Gallery and improved the Add Site flow +- Added Linux beta builds, in-app update support, and improved certificate trust handling +- Preserved custom db.php drop-ins when updating Studio’s SQLite integration +- Updated multiple dependencies, including WP Playground, PHP-Wasm, WordPress packages, and React + +## 1.9.0 + +- Introduced the Blueprints Gallery +- Shared connected WordPress.com sites between the Studio app and CLI +- Improved Studio Code remote sessions +- Added GPT 5.5 support and a scaffold\_theme tool for the CLI agent +- Improved Studio Code agent reliability +- Fixed several Studio UI, Blueprint upload, and site creation issues +- Always ask before stopping running sites when quitting Studio +- Improved Linux packaging and installer size +- Updated multiple dependencies, including WordPress packages, WP Playground, and PHP-WASM + +## 1.8.1 – CLI only + +- Added Telegram remote-session bridge for studio code (PoC) +- Added /annotate skill with Studio inspector +- Added toolbar annotations to the site preview +- Removed Studio Code turn cap handling +- Switched Agent SDK to auto permission mode +- Flag HTML block misuse during validation +- Fixed AI CLI interrupt handling and immediate turn recovery +- Linux: support installing the Studio CLI +- Improved –format=json output when no sites are found +- Fixed WP-CLI post content parsing before porcelain flags + +[View release notes](https://github.com/Automattic/studio/releases/tag/v1.8.1) + +## 1.7.11 – CLI only + +- Added PromptFoo evaluation framework for code agent +- Added log rotation for process manager children logs +- Renamed process manager home from .studio/pm2 to .studio/daemon +- Fixed Jetpack backup import using stale .ht.sqlite instead of SQL dumps + +[View release notes](https://github.com/Automattic/studio/releases/tag/v1.7.11) + +## 1.7.10 – CLI only + +- Added Opus 4.7 support to code agent +- Queued follow-up prompts during an active agent turn +- Prompted user to retry on transient API errors in code agent +- Scaffolded new Studio Code UI behind ENABLE\_STUDIO\_CODE\_UI feature flag +- Supported inline wpcom auth via STUDIO\_WPCOM\_TOKEN in code agent +- Truncated cwd in welcome header on narrow terminals +- Replaced chalk with util.styleText wrapper +- Updated default PHP version to 8.4 +- Updated multiple dependencies, including WP Playground and PHP-Wasm + +[View release notes](https://github.com/Automattic/studio/releases/tag/v1.7.10) + +## 1.7.9 – CLI only + +- Showed compaction status in code agent UI +- Added /clear command to code agent +- Added –json flag for headless NDJSON output +- Showed real-time progress feedback during push/pull from code agent +- Added push/pull/import/export MCP tools for AI agents +- Sorted code agent commands and subcommands alphabetically +- Added hosting guidance to agent instructions +- Added update notifier +- Throttled dependency update checks to once per 24h +- Stopped runtime update checks for WP-CLI and sqlite-command +- Showed clear error for non-existent WordPress versions +- Enforced minimum node version +- Ensured Studio root exists before starting code agent +- Fixed ‘Spinner is already running’ error when creating sites via CLI +- Replaced ora with picospinner +- Added Blueprint landingPage property support +- Updated multiple dependencies, including WP Playground and PHP-Wasm + +[View release notes](https://github.com/Automattic/studio/releases/tag/v1.7.9) + +## 1.8.0 + +- Added resizable sidebar +- Added `.deployignore` support for Sync to exclude files from pushes +- Added zip file support for bundled Blueprints +- Added `/rank-me-up` on-page SEO audit skill to Studio Code +- Added auto-install of Playwright Chromium for MCP tools +- Added `--all` flag to preview list command +- Misc Studio Code improvements +- Updated SQLite Database Integration to v3.0.0-rc.1 +- Fixed stale phpMyAdmin assets after Studio updates +- Fixed stale protocol handler registration on app boot +- Fixed path traversal vulnerability in .wpress extractor (reported independently by [flouciel](https://hackerone.com/flouciel) and [k4sperski](https://hackerone.com/k4sperski)) +- Fixed excessive word spacing on Linux caused by emoji-font fallback + Fixed empty window on first `npm start` in a fresh workspace +- Updated multiple dependencies, including WP Playground and PHP-Wasm + +[View release notes](https://github.com/Automattic/studio/releases/tag/v1.8.0) + +## 1.7.8 + +- Released `studio` code command +- Added push/pull and import/export commands to the CLI +- Added .deployignore support for Preview Sites to exclude files from deploys +- Redesigned titlebar: window title, button sizing, offline indicator +- Improved rendering correct error and buttons when pull failed +- Fixed SSL certificate trust nudge on non-English Windows +- Fixed blueprint local resource resolution when creating sites from the app +- Fixed account settings button opening general tab instead of account +- Fixed site sort order not preserved across app restarts +- Miscellaneous minor improvements to CLI +- Miscellaneous smaller UI improvements +- Miscellaneous dark mode improvements +- Updated multiple dependencies, including WP Playground and PHP-Wasm + +[View release notes](https://github.com/Automattic/studio/releases/tag/v1.7.8) + +*April 13, 2026* + +## 1.7.7 + +- Added dark mode support +- Added phpMyAdmin support +- Ship AI instructions with every newly created site +- Fixed issue where site status wouldn’t show up correctly in app +- Rename ‘Open site’ to ‘Open local site’ in header +- Improve Playground CLI child process error handling +- Move login into Account tab and rename settings tabs +- Migrated config files, HTTPS certificates, and WordPress dependencies `~/.studio` +- Updated multiple dependencies, including WordPress packages, and PHP-WASM + +[View release notes](https://github.com/Automattic/studio/releases/tag/v1.7.7) + +*March 27, 2026* + +## 1.7.6 + +- Added enableMultisite Blueprint step support +- Added admin credentials to interactive CLI site creation flow +- Prefilled admin email and made it mandatory during site creation +- Improved app quit reliability by always killing PM2 daemon on site stop +- Improved deeplink connection speed +- Fixed site processes opening terminals on Windows +- Fixed removing sites when site folder is already removed +- Fixed Open file in IDE to respect user’s preferred edito +- Fixed re-selecting the same file not triggering the import +- Fixed unsafe type assertions +- Renamed VS Code labels to Visual Studio Code +- Replaced pm2 and pm2-axon with homegrown solutions for process management +- Updated multiple dependencies, including Electron, Sentry, WordPress packages, and PHP-WASM + +[View release notes](https://github.com/Automattic/studio/releases/tag/v1.7.6) + +*March 16, 2026* + +## 1.7.5 + +- Added Redis and Memcached support +- Added drag-and-drop site reordering +- Added WP\_DEBUG\_LOG and WP\_DEBUG\_DISPLAY toggles in site settings +- Added support for editing admin credentials during site creation and in site settings +- Added “Open Debug Log” button in Settings and “Open Application Logs” to the Help menu +- Added a time tooltip to the pull and push completion notification +- Added Blueprint details step to the blueprint selection flow +- Made CLI site create command interactive +- Improved app quit speed by timing out site stop after 6 seconds +- Disabled Copy and Delete in context menu while a site is being added +- Fixed import to include hidden files within wp-content +- Fixed push cancellation error dialog +- Fixed Preview site and Push size validation to exclude archived-out directories +- Fixed CLI uninstall on Windows not removing bin directory +- Fixed CLI locale strings displaying in English +- Fixed toggle sidebar icon alignment after the Add Site modal +- Improved accessibility attributes in site settings +- Improved compatibility of Studio sites with legacy mu-plugin in the filesystem +- Updated multiple dependencies, including Electron, WordPress Playground, PHP-WASM, Sentry, and WordPress packages + +[View release notes](https://github.com/Automattic/studio/releases/tag/v1.7.5) + +*March 6, 2026* + +## 1.7.4 + +- Added PHP 8.5 support +- Added copy site feature to the site context menu +- Added Hungarian localization +- Added Blueprint’s defineSiteUrl support +- Added Blueprint’s blogname support to prefill site name field +- Enabled Xdebug support for all users +- Fixed an issue with site start/stop status +- Added ability to start all stopped sites +- Fixed printing JSON keys to camelCase in Studio CLI site status output +- Included additional bug fixes and maintenance updates. + +[View release notes](https://github.com/Automattic/studio/releases/tag/v1.7.4) + +*February 17, 2026* + +## 1.7.3 + +- Added Zed and Antigravity editor support +- Fixed incorrect WordPress version warning when applying Blueprints +- Fixed an issue where deleting multiple sites at once could fail +- Fixed tab selection after site deletion +- Fixed sites failing to start when Studio is installed in a path containing spaces +- Fixed Studio CLI –skip-site-details flag for already-running sites +- Included additional bug fixes and maintenance updates. + +[View release notes](https://github.com/Automattic/studio/releases/tag/v1.7.3) + +*February 3, 2026* + +## 1.7.2 + +- Added pause and resume functionality during the push process in Studio Sync +- Improved site creation speed +- Improved error details when the Studio CLI fails +- Fixed thumbnail not loading for newly created sites +- Fixed site export in offline mode +- Fixed translation of Beta Features menu items + +[View release notes](https://github.com/Automattic/studio/releases/tag/v1.7.2) + +*January 28, 2026* + +## 1.7.1 + +- Fixed Node.js permissions bug on Intel Macs +- Fixed excessive WP-CLI command invocations + +[View release notes](https://github.com/Automattic/studio/releases/tag/v1.7.1) + +*January 26, 2026* + +## 1.7.0 + +[![Settings menu in a WordPress application showing options for language, code editor, terminal application, and Studio CLI.](https://developer.wordpress.com/wp-content/uploads/2025/05/studio-enable-cli-1.jpg)](https://developer.wordpress.com/wp-content/uploads/2025/05/studio-enable-cli-1.jpg)- Expanded the [Studio CLI](https://developer.wordpress.com/docs/developer-tools/studio/cli/) + - Added site management commands + - Added authentication commands + - Added WP CLI support +- Improved Xdebug support (Beta Feature) +- Added file upload progress and offline status indicator in Sync user interface +- Increased Sync push size limit to 5GB +- Added support for Blueprint translations +- Improved performance on Mac and Windows +- Improved the speed of creating a WordPress site in online mode +- Updated SQLite plugin to 2.2.16, improving MySQL compatibility +- Included additional bug fixes and maintenance updates. + +[View release notes](https://github.com/Automattic/studio/releases/tag/v1.7.0) + +*January 23, 2026* + +## 1.6.8 + +- Made Sync uploads resumable, and improved Sync safety and feedback (including preventing site deletion during Sync and providing clearer error states). +- Added a Telex information banner to the Assistant tab. +- Improved Studio update dialogs with clearer messaging and Esc-key handling. +- The “What’s new” modal no longer appears until at least one site has been created. +- Fixed the Windows auto-updater so ARM64 installations receive the correct installer architecture. +- Disabled “Import from WordPress.com” when Studio is offline. +- Included additional bug fixes and maintenance updates. + +[View release notes](https://github.com/Automattic/studio/releases/tag/v1.6.8) + +*January 6, 2026* + +## 1.6.7 + +- Fixed issues with auto-updates. +- Fixed creation of new sites after pulling an existing site. +- Fixed plugin and theme installation in the Studio Assistant. +- Improved pulling existing sites with better loading states and fewer path conflicts. +- Improved error handling when importing invalid file formats. +- Refined the “Add Site” experience. +- Improved feedback when access is denied during authentication. +- Added app architecture information to the About dialog. + +[View release notes](https://github.com/Automattic/studio/releases/tag/v1.6.7) + +*December 15, 2025* + +## 1.6.6 + +[![Screenshot of the 'Add a site' interface in WordPress Studio, displaying options to create a new site, start from a Blueprint, pull an existing site, or import from a backup.](https://developer.wordpress.com/wp-content/uploads/2025/07/studio-changelog-166.jpg)](https://developer.wordpress.com/wp-content/uploads/2025/07/studio-changelog-166.jpg)- Added a new “Pull an existing site” flow to create a local site directly from a live WordPress.com site. +- Added a “Publish site” button to deploy local sites back to WordPress.com. +- Enabled Blueprint outputs from the built-in Studio Assistant to open directly in Studio. +- Added a toggle in Settings for installing or uninstalling the Studio CLI. +- Added a warning when pushing a site that’s running an outdated WordPress version. +- Add the ability to [launch Studio sites from a Blueprint](https://developer.wordpress.com/docs/developer-tools/studio/blueprints/open-in-wordpress-studio-button/) using deep links. +- Improved the push dialog to show the size of the selected sync. +- Improved the onboarding flow for WordPress.com authentication. +- Ensured the bundled SQLite plugin stays up to date when launching sites via the CLI. +- Fixed an issue that prevented the “Add blank site” modal from closing. +- General UI polish and performance improvements. + +[View release notes](https://github.com/Automattic/studio/releases/tag/v1.6.6) + +*December 9, 2025* + +## 1.6.5 + +- Fixed the broken WP-CLI support introduced in 1.6.4. +- Resolved update failures on Windows. +- Added beta support for multi-worker launch in the Playground CLI. +- Introduced translated progress messages for the Playground CLI. + +[View release notes](https://github.com/Automattic/studio/releases/tag/v1.6.5) + +*November 25, 2025* + +## 1.6.4 + +- Added a beta flow for creating a new site from a remote site. +- Introduced new CLI commands for logging in and out of WordPress.com. +- Added support for base64-encoded Blueprints in deeplinks. +- Updated deeplink URL scheme from `wpcom-local-dev` to `wp-studio`. +- Excluded database files from push operations for better stability. +- Improved push success emails with detailed sync information. +- Fixed issues with connected sites after login and sync option handling. +- Upgraded Playground, PHP-WASM, and SQLite dependencies. +- Miscellaneous UI and performance improvements. + +[View release notes](https://github.com/Automattic/studio/releases/tag/v1.6.4) + +*November 24, 2025* + +## 1.6.3 + +- Improved selective push and export to include all folders within `wp-content`. +- Separated staging and production sites in the Sync modal. +- Added a new developer survey in the *What’s New* modal. +- Improved terminal app detection and selection. +- Fixed RTL styling and other minor UI issues. +- Updated Electron, Playground packages, and other dependencies. + +[View release notes](https://github.com/Automattic/studio/releases/tag/v1.6.3?utm_source=chatgpt.com) + +*November 7, 2025* + +## 1.6.2 + +- You can now cancel push and pull operations, giving you more control when syncing sites. +- Added a new Beta Features menu to test experimental functionality before full release. +- Windows ARM64 builds are now supported. +- Improved the Add Site flow so you can easily revisit completed setup steps. +- Updated the sync modal design for a cleaner, more intuitive experience. +- Fixed several bugs affecting plugin downloads, preview cleanup, and window sizing. + +[View release notes](https://github.com/Automattic/studio/releases/tag/v1.6.2) + +*October 27, 2025* + +## 1.6.1 + +[![The context menu in Studio 1.6.1.](https://developer.wordpress.com/wp-content/uploads/2025/07/studio-context-menu.jpg)](https://developer.wordpress.com/wp-content/uploads/2025/07/studio-context-menu.jpg)- Added a new site context menu for quicker access to common actions in the site sidebar, as shown in the image above. +- Improved progress reporting during site imports for better clarity. +- Upgraded the bundled SQLite plugin for improved stability and compatibility. +- Fixed focus issues when switching between tabs in the app. +- Resolved broken “Customize” links in classic themes. + +[View release notes](https://github.com/Automattic/studio/releases/tag/v1.6.1) + +*October 14, 2025* + +## 1.6.0 + +![](https://developer.wordpress.com/wp-content/uploads/2025/10/studio-add-site-blueprints-16-1.jpg)- Added support for [Blueprints](https://developer.wordpress.com/docs/developer-tools/studio/blueprints/), allowing you to define plugins, themes, and settings for new sites to create consistent environments faster. This work introduces a new “**Add site**” flow featuring a dedicated screen where you can choose between adding an empty site, selecting a Blueprint, or importing a backup. + - [Learn more in our blog post](https://wordpress.com/blog/2025/10/08/introducing-blueprints-in-wordpress-studio-1-6-0/) + - [Learn how to create Blueprints](https://developer.wordpress.com/docs/guides/how-to-create-custom-blueprints/) + - [Explore the docs](https://developer.wordpress.com/docs/developer-tools/studio/blueprints/) +- Introduced Selective Syncing in the pull dialog, giving you more control over what content and code changes to sync. +- Migrated from wp-now to the [Playground CLI](https://wordpress.github.io/wordpress-playground/developers/local-development/wp-playground-cli/) for improved performance, reliability, and better parity with WordPress Playground. +- Added support for Sublime Text as an external code editor. +- Improved reliability when pushing large sites and refined export behavior to preserve information about completed exports. +- Migrated the internal bundler from Webpack to Vite, resulting in faster builds and a smoother developer experience. +- Fixed missing fonts on macOS Tahoe. +- Hid the What’s New modal for first-time users to streamline onboarding. +- Updated core dependencies, including Electron, Forge, Playground, and the SQLite plugin, to the latest versions for enhanced speed and stability. + +[View release notes](https://github.com/Automattic/studio/releases/tag/v1.6.0) + +*October 7, 2025* + +## 1.5.6 + +- We upgraded Studio’s SQLite plugin and enabled a new AST driver under the hood, helping power faster, more stable local environments. +- Studio now opens the Overview tab by default after creating or deleting a site, streamlining your workflow and reducing friction. +- We’ve improved offline functionality, so you can now delete sites and log out even without an internet connection. +- A better crash screen now appears if something goes wrong, and we fixed a startup bug that occurred when launching Studio from a read-only directory. +- Other improvements include support for sites with custom environment types, suppressed punycode warnings in both the app and CLI, and minor UI tweaks to make selective sync safer by default. + +[View release notes](https://github.com/Automattic/studio/releases/tag/v1.5.6) + +*August 7, 2025* + +## 1.5.5 + +![a screenshot of the Pull from Production modal window in WordPress Studio with Files and folders checked](https://developer.wordpress.com/wp-content/uploads/2025/07/wordpress-studio-selective-sync.jpg)- Introducing Selective Sync. No more all-or-nothing deployments. Push or pull only what you need. Ideal for shipping themes or plugins safely. + - [Learn more in our blog post](https://wordpress.com/blog/2025/07/14/selective-push-pull-wordpress-studio/) + - [Explore the docs](https://developer.wordpress.com/docs/developer-tools/studio/sync/) +- Studio by WordPress.com is now WordPress Studio, signaling a broader mission and cross-host compatibility. +- Studio now fully revokes your token on logout, helping protect your account across shared or multiple devices. + +[View release notes](https://github.com/Automattic/studio/releases/tag/v1.5.5) + +*July 14, 2025* + +## 1.5.4 + +![An orange arrow pointing to the preferences wheel in WordPress Studio](https://developer.wordpress.com/wp-content/uploads/2025/07/wordpress-studio-open-preferences.jpg)- There’s a new Settings button that makes it easier to jump straight into your Studio preferences, where you can specify your app language and default code editor and terminal application. + +[View release notes](https://github.com/Automattic/studio/releases/tag/v1.5.4) + +*June 23, 2025* + +## 1.5.3 + +- Studio now supports symlinks in Previews and Sync, making it easier to work with complex or modular project structures. +- We’ve improved site export performance, network reliability, and Windows editor detection, making Studio faster, more stable, and more intuitive across the board. +- We upgraded the Electron Forge and WordPress Playground packages. + +[View release notes](https://github.com/Automattic/studio/releases/tag/v1.5.3) + +*June 9, 2025* + +## 1.5.2 + +![The connect modal window in WordPress Studio showing WordPress.com and Pressable sites](https://developer.wordpress.com/wp-content/uploads/2025/07/wordpress-studio-sync-connect.jpg)- You can now sync Studio sites directly with Pressable staging and production sites. + - [Learn more in Pressable’s blog post](https://pressable.com/blog/build-locally-sync-seamlessly-studio-now-works-with-pressable/) + - [Explore the Pressable docs](https://pressable.com/knowledgebase/studio-for-pressable/) +- Push progress is now clearer, and an email notification will confirm when a push is successful. +- We’ve made behind-the-scenes improvements to syncing, preview limits, and plugin updates for better reliability across the board. + +[View release notes](https://github.com/Automattic/studio/releases/tag/v1.5.2) + +*May 26, 2025* + +## 1.5.1 + +![The preferences window in WordPress Studio showing drop-down menus for language, code editor, and terminal](https://developer.wordpress.com/wp-content/uploads/2025/07/wordpress-studio-editor-preferences-1.jpg)- Choose your preferred code editor (Visual Studio Code, Cursor, Windsurf, PhpStorm, or WebStorm) and terminal app (Terminal, Command Prompt, Warp, Ghostty, or iTerm2) for easy access to your Studio files. + - [Learn more in our blog post](https://wordpress.com/blog/2025/05/12/preferences-studio/) + - [Explore the docs](https://developer.wordpress.com/docs/developer-tools/studio/sites/#6--open-in-section) +- We’ve updated the default PHP version to 8.3 and made multiple Windows-specific improvements to HTTPS and certificate handling. + +[View release notes](https://github.com/Automattic/studio/releases/tag/v1.5.1) + +*May 12, 2025* + +## 1.5.0 + +![An orange arrow pointing to the Install CLI menu item in WordPress Studio](https://developer.wordpress.com/wp-content/uploads/2025/07/wordpress-studio-install-cli.jpg)- Studio now includes a CLI for managing Preview Sites so you can create, list, and delete Preview Sites right from your terminal. Perfect for developers who want to script common tasks or streamline their local workflow. + - [Explore the docs](https://developer.wordpress.com/docs/developer-tools/studio/cli/) + +[View release notes](https://github.com/Automattic/studio/releases/tag/v1.5.0) + +*May 5, 2025* + +## 1.4.0 + +- A new in-app “What’s New” popup gives you a quick look at the latest features and changes. +- The Studio sites you were working on now auto-start when you relaunch Studio, helping you pick up right where you left off. + +[View release notes](https://github.com/Automattic/studio/releases/tag/v1.4.0) + +*April 14, 2025* + +## 1.3.9 + +![the use custom domain modal window in WordPress Studio](https://developer.wordpress.com/wp-content/uploads/2025/07/wordpress-studio-use-custom-domain.jpg)- Studio now supports SSL for custom domains, allowing you to develop with SSL/HTTPS enabled and to create a more production-like environment locally. + - [Learn more in our blog post](https://wordpress.com/blog/2025/03/31/studio-custom-domains-https/) + - [Explore the docs](https://developer.wordpress.com/docs/developer-tools/studio/ssl-in-studio/#2-enabling-https-for-a-site) +- Support was added for nightly WordPress versions. +- You can now import/export a site while another local site is syncing. + +[View release notes](https://github.com/Automattic/studio/releases/tag/v1.3.9) + +*March 31, 2025* + +## 1.3.8 + +![The add site window in WordPress Studio showing drop-down menus for PHP and WordPress versions](https://developer.wordpress.com/wp-content/uploads/2025/07/studio-add-site-php-wordpress-version.jpg)- Choose the PHP and WordPress version you need when creating a site to test compatibility, reproduce bugs locally, or build for specific client requirements. + - [Learn more in our blog post](https://wordpress.com/blog/2025/03/17/studio-wordpress-php-versions/) + - [Explore the docs](https://developer.wordpress.com/docs/developer-tools/studio/sites/#Using-a-custom-domain-and-SSL) +- Added support for custom domains to test features that require proper domain names. + - [Learn more in our blog post](https://wordpress.com/blog/2025/03/31/studio-custom-domains-https/) + - [Explore the docs](https://developer.wordpress.com/docs/developer-tools/studio/sites/#Using-a-custom-domain-and-SSL) + +[View release notes](https://github.com/Automattic/studio/releases/tag/v1.3.8) + +*March 17, 2025* + +## 1.3.7 + +- We fixed a bug related to the rotatePHPRuntime setting that could cause sites to crash unexpectedly. + +[View release notes](https://github.com/Automattic/studio/releases/tag/v1.3.7) + +*March 6, 2025* + +## 1.3.6 + +- Studio now handles symlinks and custom site paths more reliably on Windows, improving compatibility with a wider range of local setups. + +[View release notes](https://github.com/Automattic/studio/releases/tag/v1.3.6) + +*March 6, 2025* + +## 1.3.5 + +- When creating a new site, Studio now suggests unique paths and names automatically, reducing confusion and preventing accidental overwrites. +- We also fixed compatibility issues with older versions of SQLite to ensure more consistent performance across different environments. + +[View release notes](https://github.com/Automattic/studio/releases/tag/v1.3.5) + +*March 4, 2025* + +## 1.3.4 + +![The Preview Sites area on WordPress Studio](https://developer.wordpress.com/wp-content/uploads/2025/07/wordpress-studio-preview-sites.jpg)- Demo Sites are now called Preview Sites. With 2 GB of space each, you can work with larger themes, more media assets, and richer content during your development process. + - [Learn more in our blog post](https://wordpress.com/blog/2025/02/24/studio-preview-sites/) + - [Explore the docs](https://developer.wordpress.com/docs/developer-tools/studio/preview-sites/) +- Tunneling is now supported, allowing you to define `WP_SITEURL` and `WP_HOME` in `wp-config.php` for external access via tools like ngrok. That means you can test Studio sites on real devices or share them temporarily for client previews and responsive testing. + - [Explore the docs](https://developer.wordpress.com/docs/developer-tools/studiofrequently-asked-questions/#11-how-can-i-use-a-tunneling-tool-ngrok-with-studio-) +- Studio docs are now [localized in Spanish](https://developer.wordpress.com/es/docs/herramientas-para-desarrolladores/studio/). + +[View release notes](https://github.com/Automattic/studio/releases/tag/v1.3.4) + +*February 24, 2025* + +## 1.3.3 + +- We added support for mu-plugins in site import, plus improvements to ZIP import, fullscreen behavior on macOS, and terminal UX on Windows. + +[View release notes](https://github.com/Automattic/studio/releases/tag/v1.3.3) + +*February 5, 2025* + +## 1.3.2 + +- Studio’s Demo Site limit is now 2 GB (up from 250 MB), giving you more space to test, gather feedback, and iterate on your local sites. +- We upgraded the Electron version powering Studio to 33.3.1. + +[View release notes](https://github.com/Automattic/studio/releases/tag/v1.3.2) + +*January 21, 2025* + +## 1.3.1 + +- Studio now supports importing a site when another one is already in progress. +- You can now select a custom domain when setting up a new WordPress.com site from the Studio UI. + +[View release notes](https://github.com/Automattic/studio/releases/tag/v1.3.1) + +*January 13, 2025* + +## 1.3.0 + +- Introducing Studio Sync, making it easy to push and pull changes between your local Studio environment and live or staging sites on WordPress.com (Business or Commerce plans). You can push local changes to production, pull down the latest version to work locally, or collaborate across teams by linking multiple Studio installs to the same hosted site. + - [Learn more in our blog post](https://wordpress.com/blog/2025/01/06/studio-sync/) + - [Explore the docs](https://developer.wordpress.com/docs/developer-tools/studio/sync/) +- We bumped the default PHP version to 8.2 and improved RTL layout handling. + +[View release notes](https://github.com/Automattic/studio/releases/tag/v1.3.0) + +*January 3, 2025* + +## 1.2.2 + +![The WordPress Studio listing in the Microsoft Store](https://developer.wordpress.com/wp-content/uploads/2025/07/wordpress-studio-microsoft-store.jpg)- Studio is now available as an AppX installer, making it easier than ever to install directly [from the Microsoft Store](https://apps.microsoft.com/detail/9pntbl35pzvs?hl=en-US&gl=US) on Windows devices. +- We’ve improved the accuracy of theme and plugin exports, so your backups are cleaner and more portable across environments. +- Sites now start automatically after import, helping you get back to development faster with fewer clicks. +- We also resolved login issues with Jetpack-enabled sites by disabling Jetpack Protect in local environments, making autologin more reliable during development. + +[View release notes](https://github.com/Automattic/studio/releases/tag/v1.2.2) + +*November 25, 2024* + +## 1.2.1 + +- We streamlined the site import process by removing unnecessary steps related to media regeneration. That means faster imports and less waiting around when setting up a site. + +[View release notes](https://github.com/Automattic/studio/releases/tag/v1.2.1) + +*November 11, 2024* + +## 1.2.0 + +![The Studio Assistant RUN button in WordPress Studio](https://developer.wordpress.com/wp-content/uploads/2025/07/wordpress-studio-assistant-run.jpg)- Meet Studio Assistant, your new built-in AI for getting the most out of Studio. With the Studio Assistant, you can quickly configure new sites, manage existing sites, and run complex WP-CLI commands, all through a simple and intuitive chat interface. + - [Learn more in our blog post](https://wordpress.com/blog/2024/10/29/studio-assistant/) + - [Explore the docs](https://developer.wordpress.com/docs/developer-tools/studio/sync/) +- We also refreshed the interface with cleaner styling and improved window handling on macOS, making Studio feel more native, modern, and responsive. + +[View release notes](https://github.com/Automattic/studio/releases/tag/v1.2.0) + +*October 29, 2024* + +## 1.1.4 + +- Studio now supports importing .wpress backup files, making it easier to bring in full site backups created with common WordPress tools. +- We’ve also improved error messages during the import process, helping you troubleshoot faster. +- You can now open the Settings menu even when you’re offline, great for tweaking preferences without needing a live connection. + +[View release notes](https://github.com/Automattic/studio/releases/tag/v1.1.4) + +*October 14, 2024* + +## 1.1.3 + +- Studio now fully supports symlinks, unlocking smoother workflows for advanced development. +- We also use the default PHP version when running the WP-CLI sqlite import command. + +[View release notes](https://github.com/Automattic/studio/releases/tag/v1.1.3) + +*September 30, 2024* + +## 1.1.2 + +- Studio is now fully responsive, making it easier to use on smaller screens or in split-view setups. +- We added a sidebar toggle to help you focus in-app, along with several quality-of-life improvements to local path handling. + +[View release notes](https://github.com/Automattic/studio/releases/tag/v1.1.2) + +*September 16, 2024* + +## 1.1.1 + +- You can now switch Studio’s language from the Settings menu, unlocking Studio usage for users around the world. +- We improved compatibility with WooCommerce and polished terminal behavior, WordPress Playground interactions, and UI details throughout the app. + +[View release notes](https://github.com/Automattic/studio/releases/tag/v1.1.1) + +*September 10, 2024* + +## 1.1.0 + +![An orange arrow pointing out the import/export section in WordPress Studio](https://developer.wordpress.com/wp-content/uploads/2025/07/wordpress-studio-import-export.jpg)- You can now export and import full WordPress sites with a single click, making it easier to move projects between machines, collaborate with teammates, or work on a production or staging site on any WordPress host. + - [Explore the docs](https://developer.wordpress.com/docs/developer-tools/studio/import-export/) +- We also added support for Ukrainian and rolled out general UI improvements. + +[View release notes](https://github.com/Automattic/studio/releases/tag/v1.1.0) + +*August 20, 2024* + +## 1.0.7 + +- We improved how Studio handles testing timers and reduced the risk of data corruption during simultaneous operations. +- A new message alerts users if their account doesn’t support Demo Sites, saving confusion during setup. + +[View release notes](https://github.com/Automattic/studio/releases/tag/v1.0.7) + +*August 5, 2024* + +## 1.0.6 + +- Studio now supports Vietnamese, expanding accessibility for more developers. +- We improved the onboarding experience by fixing issues with the Settings menu and adding subtle UI polish like hover states and loading indicators. +- Users now receive a helpful reminder to restart after checking for updates. +- The “Delete site files” checkbox is now checked by default, preventing forgotten leftovers on disk. + +[View release notes](https://github.com/Automattic/studio/releases/tag/v1.0.6) + +*July 22, 2024* + +## 1.0.5 + +- We fixed a crash that occurred when deleting sites and improved the clarity of confirmation dialogs throughout the app. + +[View release notes](https://github.com/Automattic/studio/releases/tag/v1.0.5) + +*July 8, 2024* + +## 1.0.4 + +- Windows users can now speed up sites using a new performance modal. +- We also added the ability to change the PHP version per site, great for testing across versions, and bumped the default to PHP 8.1. +- New menu links make it easier to submit feedback, and we improved translation support and fixed race conditions during site creation. + +[View release notes](https://github.com/Automattic/studio/releases/tag/v1.0.4) + +*June 17, 2024* + +## 1.0.3 + +- Studio is now available for Windows users. + - [Learn more in our blog post →](https://wordpress.com/blog/2024/05/29/studio-windows/) +- Plugin, theme, and core updates are now fully functional again, and we fixed update flows on Windows. +- We also introduced an application menu for Windows, improved Sentry logging, and squashed several platform-specific bugs. +- You can now delete all Demo Sites at once, and Studio will handle permalink structures without needing index.php. + +[View release notes](https://github.com/Automattic/studio/releases/tag/v1.0.3) + +*May 29, 2024* + +## 1.0.2 + +- We made Studio feel snappier by moving key processes to separate threads and reducing layout issues on Windows and RTL languages. +- WooCommerce and font uploads work more reliably, and external resources like YouTube now resolve correctly. +- Design tweaks across onboarding, layout, and headers polished the experience across platforms. + +[View release notes](https://github.com/Automattic/studio/releases/tag/v1.0.2) + +*May 16, 2024* + +## 1.0.1 + +- Your WordPress.com profile photo now links to your account, and Studio helps users download the right version of the app for their machine. +- We improved support for RTL languages and long translations, confirmed deletions using native OS dialogs, and resolved crashes caused by demo site status issues. +- Other improvements include a copy button for demo URLs, better keyboard navigation, smarter error handling, and more consistent drag behavior. + +[View release notes](https://github.com/Automattic/studio/releases/tag/v1.0.1) + +*May 13, 2024* + +## 1.0.0 + +- Hello, world. Welcome to Studio, local WordPress development made simpler, faster, and more accessible for everyone. + - [Learn more in our blog post](https://wordpress.com/blog/2024/04/24/studio/) + +[View release notes](https://github.com/Automattic/studio/releases/tag/v1.0.0) + +*April 29, 2024* diff --git a/content/runtime/documentation/developer-tools/studio/cli.md b/content/runtime/documentation/developer-tools/studio/cli.md new file mode 100644 index 0000000..4371bf9 --- /dev/null +++ b/content/runtime/documentation/developer-tools/studio/cli.md @@ -0,0 +1,397 @@ +--- +type: document +title: Studio CLI +description: "" +resource: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/cli/" +tags: +timestamp: "2026-06-16T19:29:22+00:00" +wordpress: + id: 2457 + status: publish + type: documentation + author: 0 + date: "2026-06-16 19:29:22" + date_gmt: "2026-06-16 19:29:22" + modified: "2026-06-16 19:29:29" + modified_gmt: "2026-06-16 19:29:29" + slug: cli + parent: 2481 + menu_order: 0 + comment_status: closed + ping_status: closed + guid: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/cli/" + comment_count: 0 +--- + +Studio CLI comes bundled with Studio, and it’s also available as a standalone npm module, [wp-studio](https://www.npmjs.com/package/wp-studio). + +If you already have Studio installed, the easiest way to try the CLI is to follow the instructions below. + +Studio CLI is a globally available command-line utility that lets you interact with [WordPress Studio](https://developer.wordpress.com/docs/developer-tools/studio/) features from your terminal, regardless of whether Studio is open or not. + +It’s especially useful for: + +- Managing local Studio sites. +- Creating and updating preview sites on WordPress.com. +- Running WP-CLI commands. +- Integrate with AI coding agents. Every site comes with an AGENTS.md file. +- Integrating Studio into scripts and build steps. + +## Installation + +1. Open the **“WordPress Studio**” application. +2. From the main menu, open the **Settings** modal. You can also click the gear icon in the top-right corner of the app. +3. Enable the **“Studio CLI**” option and click **Save**. +4. On macOS, you’ll be prompted for your account password to allow installation. + +[![Screenshot of WordPress Studio settings menu showing options for language, code editor, terminal application, and Studio CLI.](https://developer.wordpress.com/wp-content/uploads/2025/05/studio-enable-cli-1.jpg)](https://developer.wordpress.com/wp-content/uploads/2025/05/studio-enable-cli-1.jpg)## Usage + +The Studio CLI is invoked with the studio command. All commands follow the pattern: + +``` +studio [options] +``` + +You can see a high-level overview at any time with: + +``` +studio --help +``` + +[![Screenshot of a command line interface displaying the WordPress Studio CLI help menu with various commands and options.](https://developer.wordpress.com/wp-content/uploads/2025/05/studio-ai-studio-help-3.jpg)](https://developer.wordpress.com/wp-content/uploads/2025/05/studio-ai-studio-help-3.jpg)Most commands are designed to be run from the root directory of a Studio-managed site. To target a different site directory than your current working directory, use the `--path` option: + +``` +studio --path /path/to/site +``` + +## Authentication commands + +Use the `auth` commands to manage your WordPress.com authentication for Studio features that require a logged-in user (for example, preview sites). + +``` +studio auth login # Log in to WordPress.com +studio auth logout # Log out and clear WordPress.com authentication +studio auth status # Check authentication status +``` + +- `studio auth login` opens a browser-based flow to connect the CLI to your WordPress.com account. You will receive an authentication token to paste into the terminal to complete the login process. +- `studio auth status` reports whether you are currently authenticated and shows which account is in use. +- `studio auth logout` disconnects the CLI from your WordPress.com account and clears stored credentials. + +If you run a command that requires authentication (such as `studio preview create`) while logged out, the CLI will return an error and guide you to log in. + +Use the `--help` flag for detailed options on any auth command: + +``` +studio auth --help +studio auth login --help +``` + +## Preview site commands + +[Preview sites](https://developer.wordpress.com/docs/developer-tools/studio/preview-sites/) are temporary, shareable environments hosted on WordPress.com that mirror your local Studio site. Use them to share work with teammates or stakeholders without requiring a local environment. + +``` +studio preview create # Create a preview site +studio preview list # List preview sites +studio preview update # Update an existing preview site +studio preview delete # Delete a preview site +``` + +### Creating a preview site + +From the root of your local Studio site: + +``` +cd /path/to/your/studio-site +studio preview create +``` + +This will: + +- Build and upload your local site to a preview environment. +- Return a preview URL you can share with others. +- Require you to be logged in with `studio auth login`. + +You can also specify a site directory explicitly: + +``` +studio preview create --path /path/to/your/studio-site +``` + +### Listing preview sites + +To view all preview sites associated with your account: + +``` +studio preview list +``` + +This shows each preview’s host (for example, `example-preview.wpcomstaging.com`), which you’ll use with the `update` and `delete` commands. + +### Updating and deleting preview sites + +Each preview site is identified by its host name: + +``` +# Rebuild and redeploy changes from your local site to the preview site: +studio preview update +Permanently remove a preview site: +studio preview delete +``` + +Use `studio preview list` to discover the appropriate `` value if you don’t have it handy. + +For the full set of options: + +Use the `site` commands to manage local Studio sites on your machine: creating, starting, stopping, listing, and configuring them. + +``` +studio preview --help +studio preview create --help +studio preview update --help +studio preview delete --help +``` + +## Local site management commands + +You can run the `create` command from an empty directory, or a directory that already contains the files of a WordPress site, but one that’s not already listed in Studio. + +``` +studio site status # Get status of local site +studio site create # Create a new local site +studio site list # List local sites +studio site start # Start local site +studio site stop # Stop local site(s) +studio site delete # Delete local site +studio site set # Configure site settings +``` + +### Creating a local site + +To create a new local site managed by Studio: + +studio site create --https --domain hello.wp.local + +``` +# Create a new site in the current working directory, using all the default options +studio site create +Create a new site with a custom domain and HTTPS +studio site create --https --domain hello.wp.local +Create a new site in a different directory +studio site create --path /path/to/site +``` + +There are several supported flags that you can use when creating a new site. For the full set of options: + +Studio offers access to the [Blueprints Gallery](https://developer.wordpress.com/docs/developer-tools/studio/blueprints/) where you can choose and activate blueprints to create a site. The Blueprints Gallery is also available through CLI. The commands for working with blueprints are: + +studio blueprint use <blueprint-slug> --name "<site-name>" + +``` +studio site create --help +``` + +### Creating a local site using Blueprints Gallery + +studio site status + +``` +# Show all available blueprints for creating a local Studio site +studio blueprint list +Create a local site with selected blueprint +studio blueprint use --name "" +``` + +Status output includes information such as: + +### Listing and inspecting sites + +``` +# Show all local sites known to Studio: +studio site list +Show details and current status for the site in the current directory: +studio site status +Or explicitly for a given path: +studio site status --path /path/to/site +``` + +studio site delete --files + +This removes the site from Studio and, optionally, the site files from disk. + +- Whether the site is running. +- Local URL (for example, `http://localhost:PORT`). +- Key configuration details (PHP version, database status, etc.). + +### Starting and stopping sites + +``` +# From inside a site directory: +studio site start +studio site stop +Or by path: +studio site start --path /path/to/site +studio site stop --path /path/to/site +``` + +Examples of what this command can be used for include: + +To see the full list of configurable options, run: + +### Deleting a local site + +``` +# Delete a site from Studio +studio site delete +Delete the site and move the site directory to the system trash +studio site delete --files +``` + +Examples (run from your site’s root directory): + +studio wp plugin list + +### Configuring site settings + +studio wp core update-db + +``` +studio site set [options] +``` + +Key points: + +- Changing the PHP version or WordPress version. +- Adjusting the local domain or port. +- Toggling features that affect how the local environment runs. + +For a complete list of supported WP-CLI subcommands and arguments, refer to the [WP-CLI documentation](https://developer.wordpress.org/cli/commands/) or run: + +``` +studio site set --help +``` + +## Using WP-CLI through Studio + +The Studio CLI works well with AI-assisted development tools and agents such as **Claude Code**, **Cursor**, and other IDE extensions that can run shell commands on your behalf. + +``` +studio wp [] [...] +``` + +Because these tools can see your project files and execute terminal commands, they can: + +``` +# Check WordPress version: +studio wp core version +List installed plugins: +studio wp plugin list +Run database upgrades: +studio wp core update-db +``` + +*“Set up a new local WordPress site using PHP version 8.2 using Studio in this folder, start it, and tell me the local URL.”* + +Behind the scenes, the agent might run: + +- You don’t need a separate WP-CLI installation; Studio provides and configures it for you. +- Environment variables, paths, and credentials are automatically set based on the selected site, so commands operate on the correct database and files. +- You can use `--path` if you’re not in the site directory: + +``` +studio wp plugin list --path /path/to/site +``` + +This is useful when: + +``` +studio wp help +studio wp help +``` + +## Using Studio CLI with AI coding agents + +When the agent suggests a fix or change, it can also run checks using `studio wp`: + +studio wp plugin list + +- Detect that you are working in a Studio-managed WordPress project. +- Call `studio` commands automatically to manage local sites, previews, and WP-CLI tasks. +- Use command output to guide further code changes or debugging steps. + +### Typical workflows with AI agents + +You might ask: + +#### 1. Spinning up and managing a local site + +*“Run whatever WP-CLI checks you need through Studio to diagnose why the site is throwing a 500 error, then propose fixes.”* + +The agent can iteratively: + +Agents can help you set up and maintain preview environments tied to your branch or feature: + +``` +studio site create --php 8.2 +studio site start +studio site status +``` + +*“Create a preview site for this project and give me the shareable URL. Then, after each code change, update the same preview.”* + +- Quickly prototyping a new plugin or theme. +- Onboarding to an existing project where you want the agent to set up the environment for you. + +#### 2. Automated debugging and WP-CLI operations + +Which translates to: + +``` +# Run database upgrades: +studio wp core update-db +Check for current plugins: +studio wp plugin list +``` + +By combining Studio CLI with AI coding agents, you can offload much of the repetitive environment setup, testing, and deployment orchestration, and focus more on writing and reviewing your WordPress code. + +Every command and subcommand supports `--help` for inline documentation, usage, and available options. For example: + +This is the best way to explore the capabilities of the specific version of Studio CLI you have installed. + +1. Run `studio wp` commands to gather diagnostics. +2. Update code or configuration. +3. Re-run commands to verify the fix. + +#### 3. Creating and updating preview sites for review + +``` +studio auth login # if needed +studio preview create # initial deployment +studio preview update # after subsequent changes +``` + +[![A terminal window displaying a Bash command execution showing the creation of a preview site, including validation and archive creation messages, along with a link to the live site and total time taken.](https://developer.wordpress.com/wp-content/uploads/2025/05/studio-ai-create-preview-2.jpg)](https://developer.wordpress.com/wp-content/uploads/2025/05/studio-ai-create-preview-2.jpg)- Sharing progress with non-technical stakeholders. +- Collaborating with teammates who need to see live behavior without setting up a local environment. + +### Best practices when using AI agents with Studio CLI + +- **Stay in a Studio site root**: Many commands assume the current directory is a Studio-managed site. Remind your agent to `cd` into the correct folder or to use `--path`. +- **Be explicit in instructions**: When prompting an agent, mention “use the `studio` CLI” and any constraints, for example: + - “Don’t delete existing sites.” + - “Ask for confirmation before running database migrations.” + - “Only run read-only `studio wp` commands.” +- **Review destructive operations**: Commands like `studio site delete` and `studio preview delete` can remove environments. Ask the agent to show the commands it plans to run before executing them. +- **Use authentication deliberately**: For commands that require WordPress.com access (`studio auth login`, `studio preview ...`), ensure you’re comfortable with the agent initiating login flows, and confirm which account is being used. + +## Getting help + +``` +studio --help +studio auth --help +studio preview create --help +studio site start --help +studio site set --help +studio wp help +``` diff --git a/content/runtime/documentation/developer-tools/studio/debugging.md b/content/runtime/documentation/developer-tools/studio/debugging.md new file mode 100644 index 0000000..3ab3bd8 --- /dev/null +++ b/content/runtime/documentation/developer-tools/studio/debugging.md @@ -0,0 +1,74 @@ +--- +type: document +title: Debugging in Studio +description: "" +resource: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/debugging/" +tags: +timestamp: "2026-06-16T19:29:17+00:00" +wordpress: + id: 2429 + status: publish + type: documentation + author: 0 + date: "2026-06-16 19:29:17" + date_gmt: "2026-06-16 19:29:17" + modified: "2026-06-16 19:29:29" + modified_gmt: "2026-06-16 19:29:29" + slug: debugging + parent: 2481 + menu_order: 0 + comment_status: closed + ping_status: closed + guid: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/debugging/" + comment_count: 0 +--- + +WordPress Studio includes several built-in tools to help you find and fix issues in your local WordPress sites — without needing to install extra software or leave the app. + +## Debug log + +Sometimes you just need to see what WordPress is logging. Studio makes that easy with a dedicated debug log toggle that configures `WP_DEBUG` and `WP_DEBUG_LOG` for your site automatically. + +### Enabling the debug log + +1. Select the site you want to debug. +2. Navigate to the **Settings** tab. +3. Click “**Edit site**.” +4. Open the **Debugging** tab. +5. Toggle **Enable debug log** on. +6. Click **Save**. + +When the debug log is enabled, your site will capture PHP errors, notices, and warnings to `wp-content/debug.log`. An **Open log file** link will appear in the **Settings** tab, so you can jump directly to the file without hunting for its path. + +You can also write your own messages to the log using PHP’s `error_log()` function: + +``` +error_log( 'My value: ' . print_r( $my_variable, true ) ); +``` + +### Show errors in browser + +The **Debugging** tab also includes a **Show errors in browser** toggle, which sets `WP_DEBUG_DISPLAY`. When enabled, PHP errors and warnings are printed inline in the page output rather than captured silently in the log file — useful when you want immediate feedback during active development. + +Keep in mind: + +- **Show errors in browser** works best alongside the debug log, not as a replacement for it. +- Turn it off on any site you share with clients — it can expose internal path information or other implementation details in the page output. + +### Using AI agents to interpret debug logs + +Once your debug log is active, you can point an AI agent directly at it. Tell your agent — whether you’re using Claude Code, Cursor, or another tool — that error logs are available at `wp-content/debug.log`. From there, it can read the output, identify what’s going wrong, and suggest fixes without breaking your flow. + +## Database access with phpMyAdmin + +Inspecting or editing your local database used to mean a separate tool and a separate setup. Studio includes phpMyAdmin access directly from the **Overview** tab — so you can query tables, check data, and debug schema issues without leaving the app or configuring anything. + +To open phpMyAdmin for a site, select the site and click the **phpMyAdmin** button in the **Overview** tab. + +## Step-through debugging with Xdebug + +For deeper investigation, Studio includes [Xdebug](https://xdebug.org/) support. Instead of scattering debug output through your code, you can set breakpoints, step through execution line by line, and inspect variables in real time — all from your editor. + +Xdebug is available for all Studio sites and requires no system-level installation. Studio listens for debug connections on port `9003`. + +For full setup instructions, including how to connect VS Code and PhpStorm, see [Xdebug in Studio](https://developer.wordpress.com/docs/developer-tools/studio/xdebug/). diff --git a/content/runtime/documentation/developer-tools/studio/frequently-asked-questions.md b/content/runtime/documentation/developer-tools/studio/frequently-asked-questions.md new file mode 100644 index 0000000..934caf8 --- /dev/null +++ b/content/runtime/documentation/developer-tools/studio/frequently-asked-questions.md @@ -0,0 +1,272 @@ +--- +type: document +title: "WordPress Studio: Frequently asked questions" +description: "" +resource: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/frequently-asked-questions/" +tags: +timestamp: "2026-06-16T19:29:23+00:00" +wordpress: + id: 2463 + status: publish + type: documentation + author: 0 + date: "2026-06-16 19:29:23" + date_gmt: "2026-06-16 19:29:23" + modified: "2026-06-16 19:29:29" + modified_gmt: "2026-06-16 19:29:29" + slug: frequently-asked-questions + parent: 2481 + menu_order: 0 + comment_status: closed + ping_status: closed + guid: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/frequently-asked-questions/" + comment_count: 0 +--- + +On this page you’ll find answers to common questions about the [WordPress Studio](https://developer.wordpress.com/studio/) app and certain features like the [Assistant](#assistant) and [Studio Sync.](#sync) + +As a reminder, WordPress Studio is an [open source project](https://github.com/Automattic/studio) that welcomes all contributions. If you spot a bug or the Studio feature you need is missing, we have some options: + +- [Reach out to our Happiness Engineers](https://developer.wordpress.com/contact/) for specific questions about using Studio. +- [Open an issue in the repository](https://github.com/Automattic/studio/issues) to report bugs, suggest ideas, or request new features. + +## General FAQs + +Here are some answers to common questions about WordPress Studio: + +### How can I export a theme I created in WordPress Studio? + +Themes created in Studio are the same as themes created on traditional WordPress sites. You can export your theme by following these steps: + +1. Select the local site within Studio. +2. Ensure that your site is already running. +3. Click on the **Overview** tab. +4. Click the “**Site Editor**” button. +5. Once the site editor loads in your browser, expand the editor by clicking anywhere on the site preview. +6. Click the **Options** menu button in the top right of the screen, represented by the ellipsis icon (⋮). +7. Click **Export**, and your browser should begin downloading a `.zip` file of your theme. + +You can then upload your theme to any live or staging WordPress site [by following these instructions](https://wordpress.com/support/themes/uploading-setting-up-custom-themes/#upload-a-theme-file). + +### How can I publish my Studio site so that it’s publicly available? + +While [preview sites](https://developer.wordpress.com/docs/developer-tools/studio/preview-sites) are intended for sharing with clients and gathering early feedback for up to seven days, a hosting plan is required to make your site permanently accessible. + +**To publish your local site on WordPress.com**, follow the steps outlined in the [Studio Sync](https://developer.wordpress.com/docs/developer-tools/studio/sync/) doc. + +**To publish your local site on another WordPress host**, follow the [Import and Export](https://developer.wordpress.com/docs/developer-tools/studio/import-export) guide to create an export of your source site. When the export is ready, you can import that content to the destination site, for example, following the [Manually Restore Your Site from a Jetpack Backup File on WordPress.com](https://developer.wordpress.com/docs/guides/manually-restore-backup/) guide. + +### How can I manage the Studio site’s SQLite database? + +WordPress Studio uses SQLite instead of MySQL server. SQLite is a lightweight, self-contained SQL database engine that stores your database in a single file. Each of your sites will have a database file available in the following path: `wp-content/database/.ht.sqlite`. This is a hidden file and may not be visible using your File Explorer. On a Mac, you can press `cmd + shift + .` to reveal the hidden files using Finder. + +Once you’ve located the SQLite database file, you can manage the database using any application compatible with SQLite. If you’re comfortable using the command line, we recommend the [SQLite3](#SQLite3) terminal tool. Otherwise, you can use a graphical app like [SQLiteStudio](#SQLiteStudio), which gives you a user-friendly interface to work with the database. + +While connecting to the SQLite database directly can be useful for running SQL queries, the dump generated by SQLiteStudio or running “`sqlite3 wp-content/database/.ht.sqlite .dump > backup.sql`” will not be directly compatible with MySQL. + +#### SQLite3 + +SQLite is installed by default in Unix systems like Mac. For Windows, you can download it from [the official page](https://www.sqlite.org/download.html). + +Once you have it installed: + +1. Select the local site within Studio. +2. Click on the **Overview** tab. +3. Click the **Terminal** button. +4. In your terminal, execute the following command to interact with your database: + `sqlite3 wp-content/database/.ht.sqlite` + +Learn more about using SQLite3 from the terminal in [SQLite3 documentation](https://sqlite.org/cli.html). + +#### SQLiteStudio + +If you prefer using an application with a user interface, you can use [SQLiteStudio](https://sqlitestudio.pl/). + +Once you have it installed: + +1. Find the `wp-content/database/` folder in your File Explorer or Finder. +2. Make sure you can see hidden files. +3. Open SQLiteStudio. +4. Drag and drop the `.ht.sqlite` file into the application. + +### How can I use Studio with the MySQL server of my choice? + +WordPress Studio has built-in support for a SQLite database, but you can use the MySQL server of your choice, e.g., Homebrew or Docker, to test your site with different database engines. + +If you have a local site already configured to work with a custom MySQL server of your choice, you can add it to Studio. If the site files include a `wp-config.php` file, Studio will skip the SQLite database setup and use the already configured database. + +If you have already created a site in Studio, and want to switch SQLite to the MySQL server of your choice, follow the steps below: + +1. Stop the site. +2. Open your Studio’s site directory. +3. Navigate to the `wp-content` directory and delete the `db.php` file and the `database` directory. +4. Navigate to the `mu-plugins` directory and delete sqlite-database-integration-main directory. +5. Update `wp-config.php` file and fill in your MySQL server’s credentials. +6. Start the site. +7. Start your MySQL server. +8. Open the site. + +### How do I select the PHP and WordPress versions for my site? + +You can select the PHP version or the WordPress version for your site when you first create it. This option is located in the “**Advanced Settings**” section. After creating a site, the current PHP and WordPress versions are displayed in the site’s settings tab, where you can also edit and change them. + +1. Select the relevant site in the sidebar. +2. Click the **Settings** tab. +3. Click the **Edit** button in the top right corner. +4. Within the dialog, select the desired PHP and WordPress versions. +5. Click the **Save** button to persist the changes. + +### Why isn’t the “Open In” button available for my preferred app? + +For each of your local sites, the following “Open in…” options are available: + +**File Browsers:** + +- Finder (for macOS) +- File Explorer (for Windows) + +**Code Editors:** + +- VS Code +- PhpStorm +- Windsurf +- Webstorm +- Cursor + +**Terminal Applications:** + +- Terminal (for macOS) +- iTerm (for macOS) +- Warp (for macOS) +- Command Prompt (for Windows) +- Ghostty + +WordPress Studio, the code editors, and terminal applications must live in your Applications folder to ensure the **Open in…** options are available. If you haven’t selected a preferred code editor in your User Settings, no code editor button will appear in the **Open in…** area. Similarly, if no terminal application is selected, the default will be: + +- **Terminal** on macOS +- **Command Prompt** on Windows + +### How can I make Studio faster on Windows? + +If the Real-Time Protection Service of Windows Defender is enabled on your machine, it may slow down the process of creating and starting a site, particularly when running PHP files of WordPress. + +This is why WordPress Studio prompts you to “speed up site creation” when you create your first site, so an exclusion policy can be added to the Real-Time Protection Service. + +You can add this exclusion policy manually by navigating to *Help -> Want to speed up site creation?* in Studio . + +### How can I regenerate my thumbnails? + +If some thumbnails are missing after importing your site, you can regenerate them by running the following WP-CLI command: + +``` +wp media regenerate --yes --only-missing +``` + +wp media regenerate --yes --only-missingCopyCopied + +If WP-CLI isn’t installed locally, you can ask [Studio Assistant](https://developer.wordpress.com/docs/developer-tools/studio/assistant/) to run this command for you. Simply request, “Please regenerate my images using WP-CLI.” + +### How can I access Studio logs? + +Occasionally, actions like Push or Pull in the Sync tab, or Import and Export, could fail due to different reasons related to PHP, the site’s database, or custom code issue. + +If this happens, WordPress Studio will allow you to open logs and may ask to [contact support](https://developer.wordpress.com/contact/). You can also open the logs manually. + +If you use Studio on Mac: + +1. Open Terminal. +2. Enter command: + open `~/Library/Logs/Studio` +3. Locate the latest log file and open it. + +If you use Studio on Windows: + +1. Open Terminal. +2. Enter command: + `ii AppDataRoamingStudiologs` +3. Locate the latest log file and open it. + +### Is it possible to change the port or URL of my Studio site? + +By default, Studio sites are assigned a unique port starting from 8881. For example, your first Studio site uses the URL `http://localhost:8881`, and your second site uses `http://localhost:8882`. While the port of `localhost` URLs cannot be modified from Studio, you can always [use a custom domain instead of `localhost`](https://developer.wordpress.com/docs/developer-tools/studio/sites/#Using-a-custom-domain-and-SSL). + +### How can I use a tunneling tool (ngrok) with Studio? + +You can use WordPress Studio for local WordPress development that requires incoming connections by setting up a tunneling tool like [ngrok](https://ngrok.com/). ngrok, which is free to use, redirects external requests to your localhost, making your site accessible from the internet. This is especially useful for plugins like Jetpack, which default to offline mode when running locally. By using a tunneling tool, your local site can reconnect to WordPress.com, which unlocks the full capabilities of Jetpack and creates a more realistic development environment. + +Follow the steps below to set up your site for this workflow. Begin by starting your local Studio site and setting up the tunneling tool. + +If your site uses a local domain in the form of localhost:port: + +1. **Start your Studio site** and note its port (e.g., `8883`). The port can also be found on the **Settings** tab. +2. **Open a terminal** and set up [ngrok](https://dashboard.ngrok.com/get-started/setup) if you haven’t already. +3. **Set up a tunnel** to expose your local site using the following command: + `ngrok http 8883` + + If your site uses a custom local domain: + +1. **Start your Studio site** and note the domain (e.g., `my-wordpress-website.wp.local`). The domain can also be found on the **Settings** tab. +2. **Open a terminal** and set up [ngrok](https://dashboard.ngrok.com/get-started/setup) if you haven’t already. +3. **Set up a tunnel** to expose your local site using the following command: + `ngrok http --host-header=my-wordpress-website.wp.local http://my-wordpress-website.wp.local` + +When your tunnel is active, make sure to note the tunnel URL and update it in your Studio site’s WordPress configuration file. + +1. **Copy the generated tunnel URL**. It will look something like this: + `https://6xb2-12-13-14-15.ngrok-free.app` +2. **Update your WordPress configuration** (`wp-config.php`) by adding: + `define( 'WP_SITEURL', 'https://6xb2-12-13-14-15.ngrok-free.app' );` + `define( 'WP_HOME', 'https://6xb2-12-13-14-15.ngrok-free.app’ );` +3. **Refresh your site** in the browser. + +Your local Studio site should now be accessible through the tunnel URL. If it doesn’t redirect automatically, clearing your browser cache may help. You can also access the site directly by using the generated tunnel URL. + +The Local URL shown in the Settings tab will not update to reflect the new tunnel URL, and since the ngrok URL changes each time you restart the tunnel, you will need to update the `wp-config.php` file accordingly. + +To reset your local site, stop the tunnel in the terminal and shut down the Studio site. Then, remove the changes made to `wp-config.php` and restart your Studio site. It will now revert to the localhost or custom domain shown in the **Settings** tab. + +### How can I export my site for use on the WordPress playground website? + +WordPress Studio is powered by WordPress Playground. If you want to import your local site to [playground.wordpress.net](https://playground.wordpress.net/), create a ZIP file from the contents of your site folder and use the [Site Explorer](https://wordpress.github.io/wordpress-playground/web-instance#1-site-explorer) to import the ZIP in your browser. + +**Please note** that top-level entries like `wp-config.php` should live at the root of the archive. To accomplish this, select all files and directories inside the site folder when creating the ZIP file instead of the site folder itself. + +## Studio Assistant FAQs + +Here are some answers to common questions about the Studio Assistant. Please review [the Studio Assistant doc](https://developer.wordpress.com/docs/developer-tools/studio/assistant/) for step-by step instructions and helpful tips for using this feature. + +### Where do the Assistant’s answers come from? + +The Assistant leverages WordPress.com infrastructure and our WordPress knowledge base to provide helpful responses using Retrieval Augmented Generation. That’s why it needs internet connectivity and to be connected to a WordPress.com account. + +### What languages does the Studio Assistant support? + +The sample prompts you see when you first start using the Assistant will be displayed in your chosen Studio language. That said, you can talk with the Assistant in any language you prefer. + +### Can I use the Studio Assistant without a WordPress.com account? + +No, you [must log into Studio with your WordPress.com account](https://developer.wordpress.com/docs/developer-tools/studio#connect-wordpress-com) to use the Studio Assistant. This is because we use WordPress.com infrastructure to generate messages and manage access. + +### Is there any cost to use the Studio Assistant? + +It is free for any WordPress.com user, regardless of which plan you have. + +### How many prompts can I use per month? + +Each user is allowed 200 prompts per month across all of their Studio sites. If you reach this limit, you will need to wait until the next month for the prompt count to reset. + +### Where can I give feedback about the Studio Assistant’s responses? + +There are two ways to give feedback about the Assistant’s responses. + +First, there is a feedback mechanism built into the responses. Simply click **Yes** or **No** at the end of each response to help give feedback to the WordPress Studio team. + +Second, you can [write into support](https://developer.wordpress.com/contact/) to share specific feedback about the Assistant’s responses. + +## Studio Sync FAQs + +Here are some answers to common questions about the Studio Sync feature. Please review [the Studio Sync doc](https://developer.wordpress.com/docs/developer-tools/studio/sync/) for step-by step instructions and helpful tips for using this feature. + +### Why don’t my local users appear on the WordPress.com site after pushing? + +When pushing, WordPress Studio exports all your content and your entire database except for the `wp_users` and `wp_usermeta` tables. This ensures that the Jetpack-powered features on your WordPress.com website (like single sign-on or image optimization) continue working after the push. diff --git a/content/runtime/documentation/developer-tools/studio/import-export.md b/content/runtime/documentation/developer-tools/studio/import-export.md new file mode 100644 index 0000000..785adad --- /dev/null +++ b/content/runtime/documentation/developer-tools/studio/import-export.md @@ -0,0 +1,103 @@ +--- +type: document +title: "Import & export" +description: "" +resource: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/import-export/" +tags: +timestamp: "2026-06-16T19:29:23+00:00" +wordpress: + id: 2464 + status: publish + type: documentation + author: 0 + date: "2026-06-16 19:29:23" + date_gmt: "2026-06-16 19:29:23" + modified: "2026-06-16 19:29:29" + modified_gmt: "2026-06-16 19:29:29" + slug: import-export + parent: 2481 + menu_order: 0 + comment_status: closed + ping_status: closed + guid: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/import-export/" + comment_count: 0 +--- + +A WordPress Studio site can be added from a backup file that contains a site’s full content. + +An existing WordPress Studio site can be updated from the backup file in a similar fashion, or from the single `.sql` file, in the **Import / Export** tab. + +Your backup files can be downloaded from your WordPress.com site or from Jetpack’s Activity Log page. It will have the following files and directories inside: + +- `wp-config.php`: The WordPress configuration file. +- `wp-content/plugins`: The folder containing your site’s plugins. +- `wp-content/themes`**:** The folder containing your site’s themes. +- `wp-content/uploads`**:** The folder containing your site’s uploads. +- `sql/`**:** A directory with `.sql` files that contain your site’s database data. + +Exports from Studio will also have a `meta.json` file, which contains information about the desired PHP version for the site. + +Other supported formats are: + +- The `.wpress` file from the [All-in-One WP Migration and Backup plugin](https://wordpress.com/plugins/all-in-one-wp-migration) +- The `.zip` file from the [Local app](https://localwp.com/help-docs/getting-started/how-to-import-a-wordpress-site-into-local/#export-a-site) +- The `.zip` file from [WordPress Playground](https://wordpress.github.io/wordpress-playground/quick-start-guide/#save-your-site) + +If your site is hosted on WordPress.com (Business or Commerce plan) or [Pressable](https://pressable.com/), you can use [Studio Sync](https://developer.wordpress.com/docs/developer-tools/studio/sync/) as an alternative. It lets you pull down your production or staging site into Studio, and push local changes back up to the live site when you’re ready. + +## How to add a new site to WordPress Studio from a backup + +To add a new site to WordPress Studio from backup, you’ll need a `.tar.gz`, or`.zip` file: + +1. Click the “**Add site**” button in Studio. You will be presented with three options: “**Create a site**,” “**Start from a Blueprint**,” or “**Import from a backup**.” +2. Select “**Import from a backup.”** +3. On the following screen, select your backup file and click **Continue**. +4. Name your site. +5. (Optional) Toggle “**Advanced settings**” to configure additional settings. +6. Click “**Add site**.” + +Any imported site is started by default and visible in the sidebar. + +## How to update an existing WordPress Studio site from a backup + +To update an existing Studio site from a backup, you’ll need a `.tar.gz`, `.zip`, or `.sql` file: + +1. Select the site you wish to update from the Studio sidebar. +2. Open the *Import / Export* tab. +3. Click the *Import* box to select your backup file. Alternatively, you can drag and drop your backup file into the *Import* box. +4. When prompted, click **Import** to overwrite your Studio site with your backup file. + +The Studio site will be replaced from the provided `.tar.gz` or `.zip` backup. However, when you import `.sql` file to an existing site, the database dump will be imported on top of the existing site. + +## How to export a site from WordPress Studio + +WordPress Studio allows you to export your entire local site into a `.zip` format, which is compatible with Jetpack Backup. You may also export only the database into a `.sql` file, which is compatible with MySQL. + +To export a site from Studio: + +1. Select the site you wish to export from the Studio sidebar. +2. Open the *Import / Export* tab. +3. Click the “**Export entire site**” button to generate a full-site `.zip` file or the “**Export database**” file to generate a `.sql` file. +4. Choose the destination and click **Save.** + +When the export is finished, Studio will open the directory containing the backup file automatically. + +Note that `node_modules` and `.git` paths are excluded from the exported file. + +## How to upload a WordPress Studio export to a hosted WordPress site + +Once you have the backup file, you can deploy it to **any** WordPress site. For example, if your site is on WordPress.com (Business or Commerce plan), you can follow the [Manually Restore Your Site from a Jetpack Backup File on WordPress.com](https://developer.wordpress.com/docs/guides/manually-restore-backup/) guide. + +Alternatively, if your site is hosted on WordPress.com (Business or Commerce plan) or Pressable, you also have the option to use [Studio Sync](https://developer.wordpress.com/docs/developer-tools/studio/sync/). This feature lets you connect Studio to your live production or staging sites and push local changes with a single click—no manual file upload required. + +## How to import a site without a Jetpack backup + +If you are not using Jetpack Backup, you can still import the site to WordPress Studio from a backup file created manually: + +1. Create a temporary import directory e.g., `import-to-studio/`. +2. Create `sql/` and `wp-content/` directories inside the created directory. +3. Open `wp-content/` directory of your site and copy `plugins/`, `themes/`, and `uploads/` to the `wp-content/` in the temporary import directory. +4. Copy your site’s `wp-config.php` to the temporary import directory. +5. Export your site’s database using your favorite MySQL tool and place the dump file in `sql/` directory. +6. Select all files in temporary import directory and compress them as `.zip` file. +7. Follow the steps shown above to add a new site from the backup file. diff --git a/content/runtime/documentation/developer-tools/studio/index.md b/content/runtime/documentation/developer-tools/studio/index.md new file mode 100644 index 0000000..9b8c8b2 --- /dev/null +++ b/content/runtime/documentation/developer-tools/studio/index.md @@ -0,0 +1,95 @@ +--- +type: document +title: WordPress Studio +description: "" +resource: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/studio/" +tags: +timestamp: "2026-06-16T19:29:25+00:00" +wordpress: + id: 2481 + status: publish + type: documentation + author: 0 + date: "2026-06-16 19:29:25" + date_gmt: "2026-06-16 19:29:25" + modified: "2026-06-16 19:29:30" + modified_gmt: "2026-06-16 19:29:30" + slug: studio + parent: 2514 + menu_order: 0 + comment_status: closed + ping_status: closed + guid: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/studio/" + comment_count: 0 +--- + +[WordPress Studio](https://developer.wordpress.com/studio/?ref=docs) is a free desktop app for local WordPress development. Spin up [local sites](https://developer.wordpress.com/docs/developer-tools/studio/sites/) in seconds, with [SSL](https://developer.wordpress.com/docs/developer-tools/studio/ssl/) and custom local domains to match your production environment. Use [Blueprints](https://developer.wordpress.com/docs/developer-tools/studio/blueprints/) to define exactly which plugins, themes, and content each site starts with, so you can reproduce the same setup every time. + +Manage your site from the terminal with [Studio CLI](https://developer.wordpress.com/docs/developer-tools/studio/cli/), and build sites using [Studio Code](https://developer.wordpress.com/docs/developer-tools/studio/studio-code/) (early access) leveraging the power of AI.. When something breaks, [built-in debugging tools](https://developer.wordpress.com/docs/developer-tools/studio/debugging/), including a debug log, phpMyAdmin, and [Xdebug](https://developer.wordpress.com/docs/developer-tools/studio/xdebug/), help you diagnose issues without installing anything extra. + +[Sync with WordPress.com and Pressable](https://developer.wordpress.com/docs/developer-tools/studio/sync/) in both directions: pull an existing online site to work on it locally, or push any local site to production or staging when it’s ready. You can also [import from a backup](https://developer.wordpress.com/docs/developer-tools/studio/import-export/) or export your local work as a ready-to-deploy archive. Share your work in progress by pushing to a temporary [preview site](https://developer.wordpress.com/docs/developer-tools/studio/demo-sites/) with a public URL. + +Check out the video below for a brief overview. + +## Quick start + +To install Studio, visit the official [WordPress Studio page](https://developer.wordpress.com/studio/?ref=dev-doc) and download the installer for your operating system: macOS or Windows. Alternatively, you can install Studio for Windows directly from the [Microsoft Store](https://apps.microsoft.com/detail/9pntbl35pzvs). + +### Install WordPress Studio for macOS + +To install and start using Studio on macOS: + +1. [Download the correct installer](https://developer.wordpress.com/studio/?ref=dev-doc) for your computer’s specs: [Silicon or Intel](https://support.apple.com/en-us/116943). +2. Open the downloaded file. +3. Drag the Studio application to your Applications folder. +4. Double-click the Studio icon to start the Studio app. +5. Name your first site and click **Continue**. + +### Install WordPress Studio for Windows + +To install and start using Studio on Windows from Microsoft Store: + +1. Access [Studio on the Microsoft Store](https://apps.microsoft.com/detail/9pntbl35pzvs) from your Windows computer. +2. Click Install. +3. Once installed, launch Studio from your Start menu. +4. Name your first site and click **Continue**. + +To install and start using Studio on Windows from WordPress.com: + +1. [Download the Windows installer](https://developer.wordpress.com/studio/). +2. Open the setup `.exe` file. +3. Wait for Studio to install, it will launch automatically once the installation is complete. +4. Name your first site and click **Continue**. + +### Connect to WordPress.com + +By connecting your WordPress.com account to WordPress Studio, you unlock features like preview sites, syncing with WordPress.com and Pressable, and access to the Studio Assistant. It also ensures you’re ready for upcoming improvements that rely on a WordPress.com connection. + +If you don’t already have a WordPress.com account, you can [create one for free](https://wordpress.com/start/?ref=developer-docs). + +To connect Studio to WordPress.com: + +1. Click the “**WordPress.com** **Log in**” link in the top right corner of Studio. +2. A new browser window will open. Log into WordPress.com. +3. On the authorization screen, click **Approve** to connect Studio to your account. +4. Once approved, a popup will appear prompting you to open the Studio app. Click on the **“Open Studio”** button to finalize the process. + +[![A screenshot depicting the Studio app and how to connect a site from WordPress.com.](https://developer.wordpress.com/wp-content/uploads/2024/04/selective-sync-connect-site-main.jpg)](https://developer.wordpress.com/wp-content/uploads/2024/04/selective-sync-connect-site-main.jpg)Once you’ve logged into WordPress.com, the **Sync**, **Previews**, and **Assistant** tabs should display their respective action buttons, rather than showing a **“Log in to WordPress.com”** button. If they don’t, you might need to *restart* the desktop application. + +## Next steps and feedback + +We hope Studio effortlessly fits into your local development workflow. Be sure to check out our other docs about specific Studio features: + +- [Studio Sites](https://developer.wordpress.com/docs/developer-tools/studio/sites/) +- [Preview Sites](https://developer.wordpress.com/docs/developer-tools/studio/demo-sites/) +- [Studio Sync](https://developer.wordpress.com/docs/developer-tools/studio/sync/) +- [](https://developer.wordpress.com/docs/developer-tools/studio/import-export/)[Import & Export](https://developer.wordpress.com/docs/developer-tools/studio/import-export/) +- [Studio Assistant](https://developer.wordpress.com/docs/developer-tools/studio/assistant/) +- [SSL in Studio](https://developer.wordpress.com/docs/developer-tools/studio/ssl-in-studio/) +- [Studio CLI](https://developer.wordpress.com/docs/developer-tools/studio/cli/) +- [Studio Frequently Asked Questions](https://developer.wordpress.com/docs/developer-tools/studiofrequently-asked-questions/) + +WordPress Studio is an [open source project](https://github.com/Automattic/studio) that welcomes all contributions. If you spot a bug or the Studio feature you need is missing, we have some options: + +- [Reach out to our Happiness Engineers](https://developer.wordpress.com/contact/) for specific questions about using Studio. +- [Open an issue in the repository](https://github.com/Automattic/studio/issues) to report bugs, suggest ideas, or request new features. diff --git a/content/runtime/documentation/developer-tools/studio/mcp-on-studio.md b/content/runtime/documentation/developer-tools/studio/mcp-on-studio.md new file mode 100644 index 0000000..0d58da7 --- /dev/null +++ b/content/runtime/documentation/developer-tools/studio/mcp-on-studio.md @@ -0,0 +1,50 @@ +--- +type: document +title: MCP on Studio +description: "" +resource: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/mcp-on-studio/" +tags: +timestamp: "2026-06-16T19:29:17+00:00" +wordpress: + id: 2427 + status: publish + type: documentation + author: 0 + date: "2026-06-16 19:29:17" + date_gmt: "2026-06-16 19:29:17" + modified: "2026-06-16 19:29:29" + modified_gmt: "2026-06-16 19:29:29" + slug: mcp-on-studio + parent: 2481 + menu_order: 0 + comment_status: closed + ping_status: closed + guid: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/mcp-on-studio/" + comment_count: 0 +--- + +Agent instruction files tell agents how to work with a Studio site, but they do not give agents direct access to it. For that, Studio also exposes an MCP (Model Context Protocol) server that agents connect to in order to create, start, stop, and interact with your local WordPress sites. + +To connect an agent, go to **Settings → MCP** in Studio and copy the JSON configuration shown there. Add it to your agent’s MCP settings. For example, for Claude Code or Codex you can also run the connection command directly from the terminal: + +``` +{ + "wordpress-studio": { + "command": "studio", + "args": ["mcp"] + } +} +``` + +[![](https://developer.wordpress.com/wp-content/uploads/2026/04/screenshot-2026-04-17-at-11.10.34.png?w=1024)](https://developer.wordpress.com/wp-content/uploads/2026/04/screenshot-2026-04-17-at-11.10.34.png)Common configuration file locations are: + +- Claude Desktop + - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` + - Windows: `%APPDATA%Claudeclaude_desktop_config.json` +- Cursor: + - Project: `.cursor/mcp.json` + - Global `~/.cursor/mcp.json` + +See the full setup guides for [Claude Code](https://code.claude.com/docs/en/mcp), [Claude Desktop,](https://modelcontextprotocol.io/docs/develop/connect-local-servers) [Codex](https://developers.openai.com/codex/mcp), [Cursor](https://cursor.com/docs/mcp#installing-mcp-servers), [Windsurf](https://docs.windsurf.com/windsurf/cascade/mcp), [VS Code](https://code.visualstudio.com/docs/copilot/customization/mcp-servers). + +Once connected, the agent can use Studio tools such as creating sites, running WP-CLI commands, and taking screenshots, in addition to reading the instruction files and skills already present in the site directory. diff --git a/content/runtime/documentation/developer-tools/studio/preview-sites.md b/content/runtime/documentation/developer-tools/studio/preview-sites.md new file mode 100644 index 0000000..6910fb2 --- /dev/null +++ b/content/runtime/documentation/developer-tools/studio/preview-sites.md @@ -0,0 +1,117 @@ +--- +type: document +title: Preview sites in WordPress Studio +description: "" +resource: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/preview-sites/" +tags: +timestamp: "2026-06-16T19:29:23+00:00" +wordpress: + id: 2465 + status: publish + type: documentation + author: 0 + date: "2026-06-16 19:29:23" + date_gmt: "2026-06-16 19:29:23" + modified: "2026-06-16 19:29:29" + modified_gmt: "2026-06-16 19:29:29" + slug: preview-sites + parent: 2481 + menu_order: 0 + comment_status: closed + ping_status: closed + guid: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/preview-sites/" + comment_count: 0 +--- + +With WordPress Studio, you can share your work with preview sites. These preview sites are powered by [WordPress.com](https://wordpress.com/?ref=dev-doc) on a temporary domain (wp.build), and they allow you to share snapshots of your local sites with clients or team members. + +You can create up to ten preview sites at a time per WordPress.com account, and you can view the total number of preview sites you have associated with your account by clicking on your avatar within the WordPress Studio app. + +While preview sites are intended for sharing with clients and gathering early feedback for up to seven days, a hosting plan is required to make your site permanently accessible. Use the [Studio Sync](https://developer.wordpress.com/docs/developer-tools/studio/sync/) or [Import/Export](https://developer.wordpress.com/docs/developer-tools/studio/import-export/) features to connect your Studio site to a hosting plan. + +## Create a preview site + +To create a preview site: + +1. Select the local site within the Studio. +2. Click on the **Previews** tab. +3. [Log in to WordPress.com](https://developer.wordpress.com/docs/developer-tools/studio#connect-wordpress-com) if you haven’t already. +4. Click on the **Create preview site** button. + +[![A screenshot depicting the Previews tab in the Studio app.](https://developer.wordpress.com/wp-content/uploads/2025/01/studio-site-preview-site.jpg)](https://developer.wordpress.com/wp-content/uploads/2025/01/studio-site-preview-site.jpg)Your preview site should be ready to view in a few seconds, and it will be available to access publicly for seven days. + +## Rename a preview site + +You can create multiple preview sites per Studio site. To differentiate between them you can rename them inside Studio. To do so follow these steps: + +1. Select the local site within the Studio. +2. Click on the **Previews** tab. +3. Click the vertical ellipsis (⋮) in the row of your preview site. +4. Click on the **Rename** button. +5. Enter a new name. +6. Click on the **Save** button. + +[![A screenshot depicting the list of preview sites and the popover that allows you to rename each site.](https://developer.wordpress.com/wp-content/uploads/2025/01/studio-site-preview-site-rename.jpg)](https://developer.wordpress.com/wp-content/uploads/2025/01/studio-site-preview-site-rename.jpg)Your preview site will display that name in the list of preview sites, while your remote preview site name will remain unchanged. + +## Delete a preview site + +To delete a preview site: + +1. Select the local site within the Studio. +2. Click on the **Previews** tab. +3. Click the vertical ellipsis (⋮) in the row of your preview site. +4. Click on the **Delete** button. + +Your preview site will be deleted and removed from the list. + +## Update your preview site + +By design, preview sites are generated as one-time “snapshots” of your work. That said, you may synchronize local site changes with your preview site: + +1. Select the local site within Studio. +2. Click on the **Previews** tab. +3. Click the vertical ellipsis (⋮) in the row of your preview site. +4. Click **Update** and confirm. + +Your preview site will be updated with the local changes in a few seconds. This will also reset the preview site expiration date back to seven days. + +## Exclude files with `.deployignore` + +When creating or updating a preview site, Studio uploads the contents of your site’s `wp-content` directory. If your site contains files you don’t want included — such as build artifacts, vendor dependencies, or large media folders — you can create a `.deployignore` file at the root of your site directory to exclude them. + +The `.deployignore` file uses the same pattern syntax as `.gitignore`. For example: + +``` +# Exclude vendor dependencies +wp-content/plugins/my-plugin/vendor +Exclude all log files +*.log +Exclude old uploads +wp-content/uploads/2024 +Exclude a specific plugin +wp-content/plugins/wordpress-seo +``` + +You can also use negation patterns to re-include specific items: + +Note: Patterns are relative to the site root directory, not to `wp-content`. The following directories are excluded by default, even without a `.deployignore` file: `.git`, `node_modules`, `.DS_Store`, and `Thumbs.db`. + +``` +# Exclude vendor, but keep important-lib +wp-content/plugins/my-plugin/vendor/* +!wp-content/plugins/my-plugin/vendor/important-lib +``` + +Preview sites are temporary, and each preview site will be **automatically deleted after seven days from the last update**. This feature ensures that preview environments are used for short-term feedback and review purposes. + +## Preview site expiration + +To quickly delete all of your preview sites within Studio: + +## Delete all preview sites + +1. Click on your avatar within Studio. +2. Click the vertical ellipsis (⋮) next to your preview site count. +3. Click the **Delete all preview sites** button. + +[![A screenshot depicting the modal that allows you to delete all preview sites in Studio.](https://developer.wordpress.com/wp-content/uploads/2025/01/studio-site-preview-site-delete-all.jpg)](https://developer.wordpress.com/wp-content/uploads/2025/01/studio-site-preview-site-delete-all.jpg) diff --git a/content/runtime/documentation/developer-tools/studio/roadmap/beta-features.md b/content/runtime/documentation/developer-tools/studio/roadmap/beta-features.md new file mode 100644 index 0000000..581f026 --- /dev/null +++ b/content/runtime/documentation/developer-tools/studio/roadmap/beta-features.md @@ -0,0 +1,42 @@ +--- +type: document +title: Beta features in WordPress Studio +description: "" +resource: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/beta-features/" +tags: +timestamp: "2026-06-16T19:29:18+00:00" +wordpress: + id: 2437 + status: publish + type: documentation + author: 0 + date: "2026-06-16 19:29:18" + date_gmt: "2026-06-16 19:29:18" + modified: "2026-06-16 19:29:29" + modified_gmt: "2026-06-16 19:29:29" + slug: beta-features + parent: 2445 + menu_order: 0 + comment_status: closed + ping_status: closed + guid: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/beta-features/" + comment_count: 0 +--- + +WordPress Studio includes a rotating set of Beta features that offer early access to functionality still in development. These features let you explore upcoming capabilities, test them in real workflows, and share feedback before they become part of the stable Studio experience. + +## How to access Beta features + +You can enable Beta features from the **Studio → Beta Features** menu. Once enabled, any available features appear directly in the app and behave like any other part of your workflow. + +[![Screenshot of the WordPress Studio menu highlighting the Beta Features option with descriptions of available features such as Studio Sites CLI, Multi-Worker Support, and Site creation from existing remote site.](https://developer.wordpress.com/wp-content/uploads/2025/12/studio-beta-menu.png)](https://developer.wordpress.com/wp-content/uploads/2025/12/studio-beta-menu.png)Beta features change regularly throughout the Studio development process, and there may be periods when no Beta features are available in the app. + +## Announcements and feedback + +All Beta features are announced in the **Beta Features** category of [Studio GitHub Discussions](https://github.com/Automattic/studio/discussions). Each announcement includes a short description of the feature, how it works, and testing information. + +[View active Beta features](https://github.com/Automattic/studio/discussions/categories/beta-features) + +Feedback should be posted directly in the corresponding discussion thread. Keeping everything in one place makes it easier to track questions, improvements, and follow-up actions. + +Trying out Beta features is a great way to support Studio’s ongoing improvement. Your feedback helps shape what ships, what changes, and what gets prioritized next. diff --git a/content/runtime/documentation/developer-tools/studio/roadmap/index.md b/content/runtime/documentation/developer-tools/studio/roadmap/index.md new file mode 100644 index 0000000..e0bfe5a --- /dev/null +++ b/content/runtime/documentation/developer-tools/studio/roadmap/index.md @@ -0,0 +1,47 @@ +--- +type: document +title: WordPress Studio roadmap +description: "" +resource: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/roadmap/" +tags: +timestamp: "2026-06-16T19:29:20+00:00" +wordpress: + id: 2445 + status: publish + type: documentation + author: 0 + date: "2026-06-16 19:29:20" + date_gmt: "2026-06-16 19:29:20" + modified: "2026-06-16 19:29:29" + modified_gmt: "2026-06-16 19:29:29" + slug: roadmap + parent: 2481 + menu_order: 0 + comment_status: closed + ping_status: closed + guid: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/roadmap/" + comment_count: 0 +--- + +WordPress Studio is an open source local development app, with community input driving what we build. While we don’t commit to specific release dates, we aim to ship **two releases per month**: one focused on bug fixes and performance, and one introducing new features or capabilities. Occasionally, a release may take longer than two weeks if it includes a significant feature. + +Have ideas or feedback? [Submit an issue on GitHub](https://github.com/Automattic/studio/issues). + +## Actively in development + +These features are in active development and targeted for future releases. If you’re interested in an early preview of upcoming features, learn how to [enable Beta features](https://developer.wordpress.com/docs/developer-tools/studio/roadmap/beta-features/) in Studio. + +### Performance enhancements + +We’re continually integrating improvements from [WordPress Playground](https://wordpress.org/playground/) to streamline Studio’s architecture. It’s an ongoing effort to reduce overhead and make both the app and your local sites faster and more responsive with each release. + +[Discuss beta feature ->](https://github.com/Automattic/studio/discussions/2196) + +## Help shape what we build + +We want Studio to reflect the needs of the WordPress dev community. To help, you can: + +- [Download Studio](https://developer.wordpress.com/studio/) and [give us feedback](https://developer.wordpress.com/contact) +- [Test the latest Beta features](https://developer.wordpress.com/docs/developer-tools/studio/roadmap/beta-features/) +- [Report a bug or request a feature on GitHub](https://github.com/Automattic/studio/issues) +- [Subscribe to our developer newsletter](https://developer.wordpress.com/newsletter/) to stay in the loop with all things WordPress development diff --git a/content/runtime/documentation/developer-tools/studio/sites.md b/content/runtime/documentation/developer-tools/studio/sites.md new file mode 100644 index 0000000..4ce1451 --- /dev/null +++ b/content/runtime/documentation/developer-tools/studio/sites.md @@ -0,0 +1,173 @@ +--- +type: document +title: Studio sites +description: "" +resource: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/sites/" +tags: +timestamp: "2026-06-16T19:29:23+00:00" +wordpress: + id: 2466 + status: publish + type: documentation + author: 0 + date: "2026-06-16 19:29:23" + date_gmt: "2026-06-16 19:29:23" + modified: "2026-06-16 19:29:29" + modified_gmt: "2026-06-16 19:29:29" + slug: sites + parent: 2481 + menu_order: 0 + comment_status: closed + ping_status: closed + guid: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/sites/" + comment_count: 0 +--- + +A Studio site is a WordPress instance running locally on your computer, and each of your sites will be listed in the WordPress Studio sidebar. + +WordPress Studio allows you to create, maintain, and work on **unlimited local WordPress websites**. + +## Add a new site + +To add a new site to Studio: + +1. Click the “**Add site**” button in the lower-left corner of Studio to display the “**Add a site**” screen. +2. You will be presented with three options: “**Build a new site”**, “**Connect a site”**, or “**Import from a backup”**. + +[![The new "Add a site" screen in WordPress Studio.](https://developer.wordpress.com/wp-content/uploads/2025/01/new-studio-site.png?w=1024)](https://developer.wordpress.com/wp-content/uploads/2025/01/new-studio-site.png)1. For now, select the “**Build a new site”** option. +2. On the next screen, select the **“Empty site”** option to start. +3. (Optional) Toggle “**Advanced settings**” to enable the following additional settings: + - Select a custom local path + - Select a custom WordPress version + - Select a custom PHP version + - [Use a custom domain.](#Using-a-custom-domain-and-SSL) +4. Click the “**Add site**“. + +![Set the site name and configure advanced settings.](https://developer.wordpress.com/wp-content/uploads/2025/10/studio-add-site-name-settings-16-1.jpg)Any new site is started by default, which is depicted by a green dot in the sidebar: + +![A screenshot depicting the Studio app and sites list in the sidebar. Green dots indicate that the site is running.](https://developer.wordpress.com/wp-content/uploads/2025/01/studio-start-dot.jpg)### Using a custom domain and SSL + +By default, new Studio sites use `localhost`. If you prefer to use a custom domain, you can enable that option when creating the site. Studio will suggest a domain for you but you can also enter your own. Custom domains must end in `.local`. + +After clicking the “**Add site**” button, you will be prompted to enter your system password. Once confirmed, the custom domain will then point to your Studio site. + +You can optionally enable HTTPS (SSL) for your custom domain. Refer to the [“SSL in Studio” doc page](https://developer.wordpress.com/docs/developer-tools/studio/ssl-in-studio/) to learn more about this functionality. + +### Add a new site using an existing WordPress directory + +You can also add a site to Studio using an existing WordPress directory: + +1. Remove `wp-config.php` file from the existing WordPress site directory. +2. Click the “**Add site**” button. +3. Name your site, choose a path with an existing WordPress site, and click “**Add site**“. + +If you’d prefer to use an existing `wp-config.php` file, [you can follow these instructions](https://developer.wordpress.com/docs/developer-tools/studio/frequently-asked-questions/#use-studio-with-mysql-server). + +## Starting and stopping sites + +You can view any *running* site in your browser. With a *stopped site*, viewing the site in your browser will be disabled until you start it again. + +To start a site: + +1. Click on a site name from the left sidebar. +2. Click the **Start** button. + +![A screenshot depicting the Studio app and button to start a local site.](https://developer.wordpress.com/wp-content/uploads/2025/01/studio-stopped-2.jpg)Once your site is running, the button will display “Running.” You can also start your site by clicking the **“WP Admin”** or **“Open Site”** buttons. Another quick way to start your site is by hovering over the gray dot in the sidebar until it changes to a green triangle, then clicking it to start your site. + +![A screenshot depicting the Studio app and button in the site list sidebar that allows you to start or stop a site.](https://developer.wordpress.com/wp-content/uploads/2025/01/studio-start-dot-hover.jpg)To stop your site, hover over the **Running** button — it will change to a **Stop** button. Click it to stop your site. + +Alternatively, hover over the green dot in the sidebar until it turns into a red square, then click it to stop your site. + +To quickly stop *all* of your local sites from running, click the **Stop all** button at the bottom of the sidebar. + +![A screenshot depicting the Studio app and button in the site list sidebar that allows stop all sites at once.](https://developer.wordpress.com/wp-content/uploads/2025/01/studio-stop-all.jpg)### View sites + +Once you start a site, there are two different ways to view it in your browser: + +- **WP admin**: Opens your local site’s dashboard. +- **Open site**: Opens your local site’s homepage. + +You do not need a username or password to view your site’s dashboard as you will be automatically logged in. + +![A screenshot depicting the Studio app and links that allow you to open the frontend of the site or wp-admin.](https://developer.wordpress.com/wp-content/uploads/2025/01/studio-open-site.jpg)## Site overview + +Each local site has its own quick-access buttons under the **Overview** tab for easy navigation and an efficient workflow. + +[![A screenshot depicting the Overview tab in the Studio app.](https://developer.wordpress.com/wp-content/uploads/2025/01/studio-site-overview-2.jpg)](https://developer.wordpress.com/wp-content/uploads/2025/01/studio-site-overview-2.jpg)Select one of your sites and [make sure that it is running](#start-stop). Under **Customize***,* you can quickly open site setting pages with just one click. + +If you’re using a block theme on your local site, you’ll see the following options: + +- Site Editor +- Styles +- Patterns +- Navigation +- Templates +- Pages + +If you’re using a classic theme on your local site, you’ll see the following options, depending on their availability in the theme: + +- Customizer +- Menus +- Widgets + +### “Open in…” section + +Under the “**Open in…**” heading, Studio will show buttons that will open your site in the following apps if detected on your computer: + +- Finder (macOS only) +- File Explorer (Windows only) + +Additionally, Studio allows opening files in the following code editors: + +- Cursor +- PhpStorm +- Sublime Text +- VS Code +- Webstorm +- Windsurf + +You can also open your sites with several terminal applications: + +- Terminal (macOS) +- Warp (macOS) +- iTerm (macOS) +- Command Prompt (Windows) +- Ghostty + +Studio also allows you to open your site’s database with the database editor: + +- phpMyAdmin + +To select a preferred code editor or terminal application, click on the user icon in the top right corner to open **“User Settings”**. + +[![A screenshot depicting how to open the User Settings in the Studio app.](https://developer.wordpress.com/wp-content/uploads/2025/01/studio-open-preferences-2.jpg)](https://developer.wordpress.com/wp-content/uploads/2025/01/studio-open-preferences-2.jpg)Then click the **Preference** tab and make your selections. + +[![A screenshot depicting the user Setting modal in Studio.](https://developer.wordpress.com/wp-content/uploads/2025/01/studio-editor-preferences-2.jpg)](https://developer.wordpress.com/wp-content/uploads/2025/01/studio-editor-preferences-2.jpg)## Site settings + +You can view each site’s settings by selecting a site and then clicking on the **Settings** tab. + +[![A screenshot depicting the Settings tab in the Studio app.](https://developer.wordpress.com/wp-content/uploads/2025/01/studio-site-settings-2.jpg)](https://developer.wordpress.com/wp-content/uploads/2025/01/studio-site-settings-2.jpg)**Site details:** + +- **Site name**: Your local site’s name (editable). +- **Local domain**: The domain you can use to view your site in your browser, [provided your site is running](#start-stop). +- **Local path**: Where your site files are located on your computer. +- **WP Version**: The current WordPress version of your local site. +- **PHP Version**: The current PHP version used for your local site. + +**WP Admin:** + +- **Username**: The username for the admin account on your local site and can be used to log into your preview site. +- **Password**: The password for the admin account on your local site and can be used to log into your preview site. +- **Admin URL**: The login page for your local site. + +### Edit a site + +Your site’s details can be edited by clicking “**Edit site**” button in the top left corner. You can edit the site’s name and switch to different PHP and WordPress versions. + +![A screenshot depicting the "Edit site" modal on the Settings tab in the Studio app.](https://developer.wordpress.com/wp-content/uploads/2025/01/studio-edit-site-new.jpg)Please note that when selecting different PHP and WordPress versions, ensure they are compatible with the plugins and themes installed on your site. If you encounter any errors on your Studio site after making these changes, reviewing your active plugins and themes is a good first step in troubleshooting. + +### Delete a site + +You may also delete your local site by clicking the “**Delete site**” button located in the ellipsis (⋮) menu besides the **“Edit Site”** button. You’ll have the option to delete site files from your computer before confirming the deletion. + +[![A screenshot depicting the warning when deleting a local site in the Studio app.](https://developer.wordpress.com/wp-content/uploads/2025/01/studio-delete-site-2.jpg)](https://developer.wordpress.com/wp-content/uploads/2025/01/studio-delete-site-2.jpg) diff --git a/content/runtime/documentation/developer-tools/studio/ssl-in-studio.md b/content/runtime/documentation/developer-tools/studio/ssl-in-studio.md new file mode 100644 index 0000000..8ab7416 --- /dev/null +++ b/content/runtime/documentation/developer-tools/studio/ssl-in-studio.md @@ -0,0 +1,153 @@ +--- +type: document +title: SSL in Studio +description: "" +resource: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/ssl-in-studio/" +tags: +timestamp: "2026-06-16T19:29:22+00:00" +wordpress: + id: 2458 + status: publish + type: documentation + author: 0 + date: "2026-06-16 19:29:22" + date_gmt: "2026-06-16 19:29:22" + modified: "2026-06-16 19:29:29" + modified_gmt: "2026-06-16 19:29:29" + slug: ssl-in-studio + parent: 2481 + menu_order: 0 + comment_status: closed + ping_status: closed + guid: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/ssl-in-studio/" + comment_count: 0 +--- + +WordPress Studio includes support for HTTPS, allowing you to create sites with secure connections that more closely resemble production environments. This feature makes your local development experience more realistic and helps identify potential issues that might only occur with HTTPS. + +## Overview + +The SSL support feature in WordPress Studio enables: + +- Creating sites with HTTPS enabled +- Using custom domains with proper SSL certificates +- Automatic certificate management +- Browser compatibility without security warnings (when trusted) + +## How it works + +WordPress Studio implements SSL support through the following components: + +- **Certificate Authority (CA)**: Studio creates its own Certificate Authority that signs certificates for your local sites. +- **Domain Certificates**: Each site with HTTPS enabled receives its own certificate signed by the CA. +- **Certificate Trust**: The system helps you trust the certificate on your operating system. +- **HTTPS Redirection**: Traffic is automatically redirected from HTTP to HTTPS for sites with SSL enabled. + +## Enabling HTTPS for a site + +Note that HTTPS requires a custom domain, as it cannot be used with the default localhost address. + +To enable HTTPS for a new or existing site: + +1. Start by creating a new site or editing an existing site using the “**Edit site**” button on the **Settings** tab. +2. If creating a new site, toggle “**Advanced setting**” in the modal that appears. +3. Check the “**Use custom domain**” option. +4. If you have not already provided one, enter a domain name (must end with `.local`) or use the automatically generated one. +5. Check the “**Enable HTTPS**” option. + +![A screenshot depicting how to enable HTTPS when creating a new Studio site.](https://developer.wordpress.com/wp-content/uploads/2025/03/studio-custom-domain-ssl-docs.jpg)1. Click the “**Add site**” or **Save** button, depending on whether you are creating a new site or editing an existing one. +2. When prompted, give your permission for WordPress Studio to modify the system hosts file. Studio will configure everything else automatically. +3. For HTTPS connections, a root certificate authority will be generated and installed. On MacOS, you’ll need to manually install the certificate to avoid browser warnings. [Refer to the guide below for more details](#macos). +4. Navigate to your site using the custom domain. + +## Certificate Trust by platform + +### Windows + +On Windows, WordPress Studio automatically adds the CA to your system trust store. This process requires administrator privileges, so you may see a User Account Control (UAC) prompt when enabling HTTPS. + +### MacOS + +On macOS, you need to manually trust the CA. To do this, find the certificate file that Studio automatically installs on your system: + +1. Navigate to the Settings tab of the site with SSL enabled. +2. Click on the “**Trust Certificate**” link under **Site Details**. + +![](https://developer.wordpress.com/wp-content/uploads/2025/03/ssl-trust-certificate.png)1. This will open the folder containing the certificate file (`studio-ca.crt`). Double-click the file to install the certificate and automatically open the **Keychain Access** tool on your machine. +2. Locate the **WordPress Studio CA** certificate. You can filter the items by the word `studio`. + +![A screenshot depicting the Keychain Access application on a Mac and the WordPress Studio CA certificate.](https://developer.wordpress.com/wp-content/uploads/2025/03/ssl-keychain.png)1. Double-click the certificate and expand the **Trust** section. +2. Set “**Secure Sockets Layer(SSL)**” to *“***Always Trust**.” You can leave all other settings the same. + +![A screenshot depicting the Keychain Access application on a Mac and how to set the SSL setting to "Always Trust" on the WordPress Studio CA certificate.](https://developer.wordpress.com/wp-content/uploads/2025/03/ssl-certificate-always-trust.png)1. Close the dialog and enter your password to confirm. + +Once the certificate is trusted, your browser will recognize it and indicate that your HTTPS sites are secure. + +### Linux + +On Linux, Studio automatically imports the root certificate authority (CA) into the system bundle, Chromium-family user NSS databases, and existing Firefox profile NSS databases (apt, Snap, and Flatpak installs) when you click **Trust Certificate**. Most users will not need the steps below. + +Use this fallback only if auto-trust didn’t take effect. + +#### Firefox (GUI) + +1. Open `about:preferences#privacy`. +2. Scroll to **Certificates** and click **View Certificates…**. + +[![](https://developer.wordpress.com/wp-content/uploads/2025/03/cleanshot-2026-05-18-at-11.54.43402x.png?w=1024)](https://developer.wordpress.com/wp-content/uploads/2025/03/cleanshot-2026-05-18-at-11.54.43402x.png)3\. Switch to the **Authorities** tab and click **Import…**. + +1. + +[![](https://developer.wordpress.com/wp-content/uploads/2025/03/cleanshot-2026-05-18-at-11.54.52402x.png?w=1024)](https://developer.wordpress.com/wp-content/uploads/2025/03/cleanshot-2026-05-18-at-11.54.52402x.png)4\. Select `~/.studio/certificates/studio-ca.crt`. + +5\. Check **Trust this CA to identify websites** and click **OK**. + +1. + +[![](https://developer.wordpress.com/wp-content/uploads/2025/03/cleanshot-2026-05-18-at-11.55.19402x.png?w=1024)](https://developer.wordpress.com/wp-content/uploads/2025/03/cleanshot-2026-05-18-at-11.55.19402x.png)6\. Fully quit and relaunch Firefox. + +1. + +#### Chromium / Chrome / Brave / Edge (CLI) + +Install `certutil` if it isn’t already available: + + ```shell +sudo apt install libnss3-tools +``` + + + + + +Import the CA into the user NSS database: + + ```shell +certutil -d sql:$HOME/.pki/nssdb -A -t 'C,,' -n 'WordPress Studio CA' -i ~/.studio/certificates/studio-ca.crt +``` + + + + + +For Snap-Chromium, use the Snap-specific NSS database path instead: + + ```shell +certutil -d sql:$HOME/snap/chromium/current/.pki/nssdb -A -t 'C,,' -n 'WordPress Studio CA' -i ~/.studio/certificates/studio-ca.crt +``` + + + + + +Fully quit and relaunch the browser after import. + +## Troubleshooting + +### Browser security warnings + +If you see browser security warnings when visiting your HTTPS-enabled site: + +- Ensure you’ve trusted the **WordPress Studio CA** certificate on your system. +- Restart your browser after trusting the certificate. +- Clear your browser cache if warnings persist. diff --git a/content/runtime/documentation/developer-tools/studio/studio-code.md b/content/runtime/documentation/developer-tools/studio/studio-code.md new file mode 100644 index 0000000..97464a2 --- /dev/null +++ b/content/runtime/documentation/developer-tools/studio/studio-code.md @@ -0,0 +1,233 @@ +--- +type: document +title: Studio Code +description: "" +resource: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/studio-code/" +tags: +timestamp: "2026-06-16T19:29:17+00:00" +wordpress: + id: 2428 + status: publish + type: documentation + author: 0 + date: "2026-06-16 19:29:17" + date_gmt: "2026-06-16 19:29:17" + modified: "2026-06-16 19:29:29" + modified_gmt: "2026-06-16 19:29:29" + slug: studio-code + parent: 2481 + menu_order: 0 + comment_status: closed + ping_status: closed + guid: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/studio-code/" + comment_count: 0 +--- + +Studio Code is currently in early access. Features, capabilities, and usage limits may change as it evolves. + +Studio Code is an AI-powered coding agent built into the [Studio CLI](https://developer.wordpress.com/docs/developer-tools/studio/cli/). It gives you an interactive chat in your terminal where you can build, customize, and manage WordPress sites conversationally, creating themes, editing files, running WP-CLI commands, deploying previews and publishing your site, all through natural language. + +## Getting started + +Studio Code is available as part of the standalone Studio CLI npm package. + +If you have the Studio desktop app installed with the [CLI enabled](https://developer.wordpress.com/docs/developer-tools/studio/cli/#0-installation), you can directly use `studio code` from the terminal. + +You can run it directly with `npx`: + +``` +npx wp-studio@latest code +``` + +And can install it globally to use `studio code` directly: + +``` +npm i -g wp-studio@latest +studio code +``` + +### Connect to WordPress.com + +By default, Studio Code uses WordPress.com infrastructure to generate AI responses. Log in to WordPress.com to get started: + +1. Run studio code from your terminal. +2. Type /login in the chat. +3. A browser window will open. Log into your WordPress.com account and approve the connection. +4. Paste the authorization token back into the terminal to complete the login. + +Alternatively, you can use your own Anthropic API key by typing /api-key in the chat. + +## Using Studio Code + +Once launched, Studio Code presents an interactive chat interface in your terminal. Type your request in natural language and the AI agent will carry it out, creating files, running commands, and making changes to your site. + +You can press the ↓ arrow to select your Studio sites, or ↓ and → to select your WordPress.com remote sites. + +### Example workflows + +**Create a new site and customize it:** + +``` +> Create a new WordPress site called "My Portfolio" with PHP 8.2 + +> Build a minimal portfolio theme with a dark color scheme + +> Add a homepage with a hero section and project grid +``` + +**Work with an existing site:** + +``` +studio code +``` + +**Share your work:** + +``` +> Create a preview site so I can share this with my client + +> Update the preview site with my latest changes +``` + +**Publish your work:** + +``` +> Publish "My Portfolio" site to examplesite.com +``` + +The agent can read and write files in your site directory, run WP-CLI commands, take screenshots of your site, and push changes to WordPress.com, all based on your instructions. + +### Slash commands + +While chatting, you can use slash commands for quick actions: + +| **Command** | **Description** | +|---|---| +| `/browser` | Open the active site in your browser | +| `/login` | Log in to WordPress.com | +| `/logout` | Log out of WordPress.com | +| `/api-key` | Set or update your Anthropic API key | +| `/model` | Switch the AI model (Sonnet or Opus) | +| `/provider` | Switch between WordPress.com and Anthropic API | +| `/preview` | Push the active site to WordPress.com as a preview | +| `/need-for-speed` | Run a performance audit on your site | +| `/annotate` | Open a visual inspector to annotate page elements and give the AI agent instructions | +| `/exit` | Exit the chat | + +### AI providers + +You can choose how AI responses are generated: + +- **WordPress.com** (default): uses your WordPress.com account. No additional setup required beyond logging in. Limits will change after early access. +- **Anthropic API key**: uses your own API key for direct access to Claude. Set it with the /api-key command. + +Switch providers with the `/provider` command. + +### AI models + +Studio Code supports two AI models: + +- **Claude Sonnet 4.6** (default): fast and efficient for most tasks. +- **Claude Opus 4.6**: more capable for complex, multi-step tasks. + +Switch models at any time with the `/model` command. + +### Visual Inspector + +`/annotate` opens your active site in a browser window with an annotation toolbar. Click “Annotate”, then click any element on the page and type an instruction. You can annotate multiple elements in one session — picking mode stays on after each save. When you’re done, click Done and the browser closes automatically. + +The agent then prints a numbered summary of your annotations and asks for confirmation before making any file edits. + +## Sessions + +Studio Code automatically saves your conversation history so you can pick up where you left off. + +### Resume a session + +``` +studio code sessions list                  # View all saved sessions + +studio code sessions resume                # Interactive picker + +studio code sessions resume latest         # Resume the most recent session + +studio code sessions resume           # Resume a specific session by ID +``` + +### Delete a session + +``` +studio code sessions delete                # Interactive picker + +studio code sessions delete           # Delete a specific session +``` + +### Disable session recording + +If you prefer not to save conversations, use the –no-session-persistence flag: + +``` +studio code --no-session-persistence +``` + +## What Studio Code can do + +Studio Code has access to a set of tools that let the AI agent interact with your WordPress environment: + +**Site management** + +- Create, start, stop, and delete local sites. +- List all local sites and view site details. + +**File operations** + +- Read, create, and edit theme and plugin files. +- Search files by name or content. + +**WordPress CLI** + +- Run any WP-CLI command (install plugins, manage posts, update settings, etc.). + +**Content validation** + +- Validate generated block content for correctness. + +**Screenshots and performance** + +- Take screenshots of your site (desktop and mobile). +- Run performance audits with Lighthouse-style metrics. + +**Preview sites** + +- Create, update, and delete preview sites on WordPress.com. + +**Sync** + +- Push your local site to WordPress.com. +- Pull a WordPress.com site to your local environment. + +**Import and export** + +- Import and export site backups. + +## Command reference + +``` +studio code                                # Start a new chat session + +studio code --path /path/to/site           # Start with a specific site directory + +studio code --no-session-persistence       # Start without saving the session + +studio code sessions list                  # List saved sessions + +studio code sessions resume [id]           # Resume a session + +studio code sessions delete [id]           # Delete a session +``` + +For the full set of options: + +``` +studio code --help +``` diff --git a/content/runtime/documentation/developer-tools/studio/sync.md b/content/runtime/documentation/developer-tools/studio/sync.md new file mode 100644 index 0000000..5f9ffcb --- /dev/null +++ b/content/runtime/documentation/developer-tools/studio/sync.md @@ -0,0 +1,131 @@ +--- +type: document +title: Studio Sync +description: "" +resource: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/sync/" +tags: +timestamp: "2026-06-16T19:29:24+00:00" +wordpress: + id: 2467 + status: publish + type: documentation + author: 0 + date: "2026-06-16 19:29:24" + date_gmt: "2026-06-16 19:29:24" + modified: "2026-06-16 19:29:29" + modified_gmt: "2026-06-16 19:29:29" + slug: sync + parent: 2481 + menu_order: 0 + comment_status: closed + ping_status: closed + guid: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/sync/" + comment_count: 0 +--- + +The Studio Sync feature allows you to synchronize a production or staging site with your WordPress Studio sites in either direction. This guide explains how to connect, pull, and push sites using Studio Sync. + +This feature is available for all WordPress.com sites on paid plans and [Pressable sites](https://pressable.com/knowledgebase/studio-for-pressable/) with Jetpack enabled. + +If you’re on a WordPress.com plan, [make sure to activate your plan features](https://wordpress.com/support/activate-your-business-plan/). Commerce plan sites are automatically activated. For sites on the Free or Pro (legacy) plans, [upgrade your plan](https://wordpress.com/support/manage-purchases/upgrade-your-plan/) to access Studio Sync. + +## Compatible sites + +### Studio Sync and Jetpack Backups + +Studio Sync relies on [Jetpack Backups](https://jetpack.com/support/backup/) to operate. To enable this, your site must have one of the following plugins activated and connected to WordPress.com: + +- VaultPress Backup +- Jetpack Security +- Jetpack Complete + +Studio Sync supports sites up to 5GB in size. If your site exceeds this limit, you’ll see a warning in the app. You can still sync specific portions of your site ([see below](#push)) as long as the total size of the selected content is under 5GB. + +### WordPress.com sites + +You can use Studio’s syncing feature on sites with a paid WordPress.com plan — no additional setup is required. + +### Pressable sites + +The Jetpack Security plugin is included on Pressable sites, but you’ll need to activate and connect it manually. To sync a Pressable site with WordPress Studio, make sure you use the same WordPress.com account in both Studio and Jetpack on the Pressable site. If the accounts don’t match, the site won’t appear as an option to connect in Studio. + +For detailed instructions on how to use Studio with Pressable sites, please refer to the [Pressable documentation](https://pressable.com/knowledgebase/studio-for-pressable/). + +## Connect WordPress Studio to an existing WordPress.com site + +You can connect your Studio sites with any WordPress.com-hosted sites [for which you are an Administrator](https://developer.wordpress.com/docs/platform-features/user-management/#roles) and synchronize the content in either direction. Studio will save the connection details, so you can easily pull your site from WordPress.com and then push the changes you made in Studio back to the original site. + +To connect a local Studio site to an existing production or staging site on WordPress.com: + +1. Select the site you wish to connect from the Studio sidebar. +2. Open the **Sync** tab. +3. [Log in to WordPress.com](https://developer.wordpress.com/docs/developer-tools/studio#connect-wordpress-com) if you haven’t already. +4. Click the “**Connect site**” button to see available sites. +5. Select the site you want to connect to and confirm by clicking the **Connect** button. + +![A screenshot depicting the modal that allows you to connect a local Studio site to a production or staging site on WordPress.com.](https://developer.wordpress.com/wp-content/uploads/2025/01/selective-sync-connect.jpg)If you’re working in a team, your teammates can repeat the same steps to collaborate on the same site. + +## Connect WordPress Studio to a new WordPress.com site + +If you’d like to push your local site to a new WordPress.com-hosted site or [staging site](https://wordpress.com/support/how-to-create-a-staging-site/), you can purchase a WordPress.com hosting plan and set up Studio Sync all at once: + +1. Select the site you wish to connect from the Studio sidebar. +2. Open the **Sync** tab. +3. Click the “**Create new site**” button to add a new site in the browser. +4. Select a plan for a new site and complete the checkout. +5. When the new site is added, accept the prompt to open Studio or click “**Connect Studio**” on your site’s Home screen. + +Studio saves the connection to let you easily synchronize the Studio site with the connected WordPress.com site in either direction. + +## Pull a WordPress.com site into WordPress Studio + +To start working on your WordPress.com site locally, first, ensure that you pull your production or [staging site](https://wordpress.com/support/how-to-create-a-staging-site/) to Studio: + +1. Select the site you wish to synchronize from the Studio sidebar. +2. Open the **Sync** tab. +3. Locate the connected WordPress.com site or connect to another one. +4. Click **Pull** to open the sync modal. + +[![A screenshot depicting the Pull process in Studio Sync. ](https://developer.wordpress.com/wp-content/uploads/2025/01/selective-sync-pull-specific-folders-v2.jpg)](https://developer.wordpress.com/wp-content/uploads/2025/01/selective-sync-pull-specific-folders-v2.jpg)1. Choose to sync **“All files and folders”** or **“Specific files and folders”**. +2. Select the elements you want to synchronize to your production or staging environment. You can expand the `plugins`, `themes`, and `uploads` folders to select individual items. +3. Decide whether to include the **Database** in the sync. +4. Confirm the **Pull** action. + +The Studio site will be replaced by the selected elements (like plugins or themes) and content (like media files and the database) from the remote WordPress.com. You can work on your site locally now, and the Studio site will be ready to be pushed to the live site anytime. + +## Push a WordPress Studio site to a WordPress.com site + +When you are happy with the changes made to your Studio site, you can synchronize local changes to your WordPress.com site or [staging site](https://wordpress.com/support/how-to-create-a-staging-site/): + +1. Select the site you wish to synchronize from the Studio sidebar. +2. Open the **Sync** tab. +3. Locate the connected WordPress.com site or connect to another one. +4. Click **Push** to open the sync modal. + +![A screenshot depicting the Push process in Studio Sync. ](https://developer.wordpress.com/wp-content/uploads/2025/01/selective-sync-push-specific-files.jpg)1. Choose to sync **“All files and folders”** or **“Specific files and folders”**. +2. Select the elements you want to synchronize to your production or staging environment. You can expand the `plugins`, `themes`, and `uploads` folders to select individual items. +3. Decide whether to include the **Database** in the sync. +4. Confirm the **Push** action. + +The selected elements of your WordPress.com site will be replaced by the files (like plugins or themes) and content (like media files and the database) from the Studio site. + +Note that the syncing process will replace the whole database of your live site. If it’s a WooCommerce site, it would include orders, product changes, and customer data. Studio triggers a full site backup before sync so you can restore your site if you are not happy with the sync result, but use it with extra caution. + +### Exclude files with .deployignore + +When pushing a Studio site to WordPress.com or Pressable, Studio honors the same `.deployignore` file [used by Preview Sites](https://developer.wordpress.com/docs/developer-tools/studio/preview-sites/#4-exclude-files-with-deployignore). Place a `.deployignore` file at the root of your site directory to exclude files from the push — for example, build artifacts, vendor dependencies, or large media folders. + +The file uses the same .gitignore-style syntax. See the [Preview Sites documentation](https://developer.wordpress.com/docs/developer-tools/studio/preview-sites/#4-exclude-files-with-deployignore) for the full syntax reference and examples. + +In addition to the defaults applied by Preview Sites (`.git`, `node_modules`, `.DS_Store`, `Thumbs.db`), Sync also excludes Studio-internal files that +shouldn’t be uploaded to the remote site: + +``` +database +db.php +debug.log +sqlite-database-integration +cache +``` + +Excluded files are hidden from the file tree in the Sync dialog and omitted from the archive uploaded to the remote site. diff --git a/content/runtime/documentation/developer-tools/studio/xdebug.md b/content/runtime/documentation/developer-tools/studio/xdebug.md new file mode 100644 index 0000000..9398b4b --- /dev/null +++ b/content/runtime/documentation/developer-tools/studio/xdebug.md @@ -0,0 +1,93 @@ +--- +type: document +title: Xdebug in WordPress Studio +description: "" +resource: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/xdebug/" +tags: +timestamp: "2026-06-16T19:29:18+00:00" +wordpress: + id: 2435 + status: publish + type: documentation + author: 0 + date: "2026-06-16 19:29:18" + date_gmt: "2026-06-16 19:29:18" + modified: "2026-06-16 19:29:29" + modified_gmt: "2026-06-16 19:29:29" + slug: xdebug + parent: 2481 + menu_order: 0 + comment_status: closed + ping_status: closed + guid: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/xdebug/" + comment_count: 0 +--- + +[Xdebug](https://xdebug.org/) is a debugging extension for PHP that enables you to set breakpoints, inspect variables, and step through your code. WordPress Studio includes Xdebug support, powered by WordPress Playground’s WebAssembly version of PHP. + +## Enabling Xdebug + +1. Select the site you want to debug. +2. Navigate to the **Settings** tab. +3. Click “**Edit site**.” +4. Check the “**Enable Xdebug**” checkbox. +5. Click **Save**. + +The site will restart automatically with Xdebug enabled. + +## Important limitations + +- **Only one site at a time**: Xdebug can only be enabled for a single site at once. To enable it for a different site, you must first disable it on the current site. +- **Performance impact**: Xdebug may slow down site performance. Disable it when not actively debugging. + +## Using Xdebug with your IDE + +Once Xdebug is enabled for a site, you can connect your IDE (code editor) to debug WordPress plugins, themes, and core code. + +### Visual Studio Code setup + +1. Install the [PHP Debug extension](https://marketplace.visualstudio.com/items?itemName=xdebug.php-debug). +2. Create a `.vscode/launch.json` file in your project with the following configuration: + +``` +{ + "version": "0.2.0", + "configurations": [ + { + "name": "Listen for Xdebug", + "type": "php", + "request": "launch", + "port": 9003, + "pathMappings": { + "/wordpress": "${workspaceFolder}" + } + } + ] +} +``` + +1. Set breakpoints in your code. +2. Start the debugging session in Visual Studio Code (**Run** → **Start Debugging**). +3. Navigate to your site in the browser to trigger the breakpoints. + +### PhpStorm Setup + +1. Go to **Settings** → **PHP** → **Debug**. +2. Verify that the Xdebug port is set to **9003**. +3. To stop breaking at the first line: + - Disable “Force break at first line when no path mapping specified” + - Disable “Force break at first line when a script is outside the project” +4. Navigate to **Settings** -> **PHP → Servers** and configure mapping for your site’s server: + - Host: localhost:8884 + - Port: 80 + - File directory: /Users/USERNAME/Studio/SITEDIR + - Absolute path on the server: `/wordpress` +5. Enable “**Start listening for PHP Debug Connections**” from the toolbar. +6. Set breakpoints in your code. +7. Navigate to your site in the browser to trigger the breakpoints. + +## Learn more + +For additional information about Xdebug integration, see the [WordPress Playground Xdebug documentation](https://wordpress.github.io/wordpress-playground/developers/xdebug/introduction). + +Studio does not support WordPress Playground’s experimental flags or Chrome DevTools integration at this time. diff --git a/content/runtime/documentation/developer-tools/wp-cli/common-commands.md b/content/runtime/documentation/developer-tools/wp-cli/common-commands.md new file mode 100644 index 0000000..8b26904 --- /dev/null +++ b/content/runtime/documentation/developer-tools/wp-cli/common-commands.md @@ -0,0 +1,392 @@ +--- +type: document +title: Common commands +description: "" +resource: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/common-commands/" +tags: +timestamp: "2026-06-16T19:29:23+00:00" +wordpress: + id: 2460 + status: publish + type: documentation + author: 0 + date: "2026-06-16 19:29:23" + date_gmt: "2026-06-16 19:29:23" + modified: "2026-06-16 19:29:29" + modified_gmt: "2026-06-16 19:29:29" + slug: common-commands + parent: 2513 + menu_order: 0 + comment_status: closed + ping_status: closed + guid: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/common-commands/" + comment_count: 0 +--- + +There are a number of commands that you may find helpful when working with your site. These commands and their common parameters are included below. There are also many other useful commands available, and these sections do not include them all. Please refer to the [WordPress.org Developer CLI Commands Guide](https://developer.wordpress.org/cli/commands) for more information. + +In the CLI itself you can also make use of the help command to find more information about what parameters and flags are available. + +For example: `wp help plugin` + +## Manage Users + +Use the following commands to manage your site’s local users. Please keep in mind that changing user aspects in CLI will not change the settings for WordPress.com user accounts that may be associated with local accounts. + +The user serving as your primary Jetpack connection must have an email that matches the email of the site owner’s WordPress.com account. If the email does not match, the site’s Jetpack Connection will not work correctly. The username does not need to match. + +### wp user list + +List all users on the site. If you have many users you may wish to restrict the list to specific roles by using the `--role` flag: + +``` +wp user list –role=adminstrator +``` + +wp user list –role=adminstratorCopyCopied + +### wp user get {USER ID/NAME/EMAIL} + +Return a specific user, either by user id, username, or email address. + +### wp user create {NAME} {USER EMAIL} –role={ROLE} + +Create a new user with the name, user email, and role defined. + +This command does not create a matching WordPress.com user. If you are using [WordPress.com Secure Sign-On (SSO)](https://wordpress.com/en/support/wordpress-com-secure-sign-on-sso/) you should instead create the local user by inviting a user via *Users > Add New*. This will ensure a WordPress.com account and local user are both created. + +### wp user update {USER ID/NAME/EMAIL} –{KEY}={VALUE} + +Update a user based on the user ID, name, or email. Updates the set of key/value pairs specified. + +Keys include `display_name`, `user_email`, `role`, and `user_pass` + +Note: You will not be able to update a user’s `user_login` with the `wp user update` command. Instead, updating the `user_login` requires using `wp search-replace`. This change, however, is not recommended as it performs partial replacements. For example: If there are two users with the usernames “techie” and “nontechie”, replacing “techie” with “sense” will result in “sense” and “nonsense”. + +If you would still like to replace a `user_login` the command to use is: + +``` +wp --skip-plugins --skip-themes search-replace "old username" "new username" *users --include-columns=user_login,user_nicename --dry-run +``` + +wp --skip-plugins --skip-themes search-replace "old username" "new username" \*users --include-columns=user\_login,user\_nicename --dry-runCopyCopied + +## Manage Plugins and Themes + +Use the following commands to manage your plugins and themes. When working with plugins and themes, please note that the related slug will not always match the plugin/theme name. + +If you are having issues with a plugin or theme you can start your command with `wp --skip-themes --skip-plugins` to run the commands despite conflicts. + +You can find [more information about skip commands below](#skipping). + +### wp plugin/theme list + +List all the plugins/themes installed on the site and their status. From these lists you will find the slugs of your installed plugins and themes, which you can use for the purpose of running the commands below. + +### wp plugin/theme activate {SLUG} + +Activate the specified plugin/theme. + +To deactivate a theme, you need to activate another in its place. + +### wp plugin deactivate {SLUG} + +Deactivate the specified plugin. + +### wp plugin/theme delete {SLUG} + +Delete the specified plugin/theme. + +You cannot delete an active theme or managed themes with this command. To remove an active theme, switch to a different theme first, then delete the theme that you want. To remove managed themes, [you may do so via SFTP](https://wordpress.com/support/sftp/). + +### wp plugin/theme install {SLUG or URL TO INSTALLATION\_FILE} + +Install a plugin/theme from the WordPress.org repo based on the slug or via a URL path to an installation .zip file. + +You can not overwrite an existing plugin/theme unless you run the command with the `--force` flag. You can use this to update plugins and fix corrupt plugin folders. + +To automatically activate a plugin after installation, include the `--activate` flag. + +### wp plugin/theme update {SLUG} + +Update the specified plugin/theme if available. You cannot use this command to update managed plugins/themes. + +You can also use the `--all` flag if you want to update all plugins/themes. + +### wp plugin auto-updates {COMMAND} {PLUGIN SLUG} + +Display the status of plugin updates or enable/disable updates for a specific plugin. + +Available COMMANDS are `status`, `enable`, `disable`. + +You cannot disable updates for managed plugins or themes. + +## Manage Jetpack + +Use the following commands to adjust Jetpack modules, check your Jetpack connection, or troubleshoot Jetpack issues. + +Disconnecting Jetpack will disable many important WordPress.com features including general site and billing management. + +Using `--skip-plugins` will prevent these commands from working. + +You can find [more information about skip commands below](#skipping). + +### wp jetpack module list + +List the Jetpack modules and their statuses. + +### wp jetpack module activate {MODULE NAME} + +Activate the specified Jetpack module. + +You can also use `all` in place of {MODULE NAME} + +### wp jetpack module deactivate {MODULE NAME} + +Deactivate the specified Jetpack module. + +You can also use `all` in place of {MODULE NAME} + +### wp jetpack status + +Report the status of Jetpack, including which user account is the primary connection (this should always be the site owner). + +An additional parameter, `full`, can be added to report full details, including Jetpack version, WordPress version, and module status. + +While your [site’s visibility is set to Private](https://wordpress.com/support/privacy-settings/#privacy-options), some Jetpack modules are disabled and cannot be managed in CLI. These modules are: Ads, Asset CDN, Enhanced Distribution, Google Analytics, Image CDN, JSON API, Publicize, Sharing, Site Verification, and Sitemaps. + +## Manage Site Settings + +Use the following commands to manage various aspects of your site and users. + +### wp site empty –yes + +Empty a site of content (posts and pages). + +### wp site empty –uploads –yes + +Empty the site, including media files. + +`wp site empty` commands are irreversible. If you use them, your content will be removed permanently. To recover them, [you will need to restore from a previous backup](https://developer.wordpress.com/docs/platform-features/real-time-backup-restore/). Please ensure you have a backup available before using the function. + +`wp site` commands will not delete themes or plugins, nor will they reset a theme or erase plugin settings. If you need to reset your site completely, [please reach out to WordPress.com support](https://developer.wordpress.com/docs/glance/support/). + +### wp option get {OPTION} + +Return the value of an option. + +### wp option update {OPTION} {VALUE} + +Update the value of an option. + +### wp option add {OPTION} {VALUE} + +Add a new option. + +### wp option delete {OPTION} + +Delete an option. + +The options table is the “control center” of a website. If an option is improperly edited or deleted, you may stop your entire site from working. + +When working with `wp option` commands, if you get the following error in the terminal it may mean the options table has been corrupted: + +``` +One or more database tables are unavailable. The database may need to be repaired +``` + +One or more database tables are unavailable. The database may need to be repaired + +You can restore the table by rewinding the site’s SQL table to a last good copy. Please note, this will reverse all mutable changes to the database that occur after the restore point and can result in lost data. + +To restore an SQL table: + +1. In the site’s dashboard, navigate to **Jetpack > Activity Log**. +2. Select a [backup point](https://developer.wordpress.com/docs/platform-features/real-time-backup-restore/) to rewind to. +3. Uncheck all boxes except for **Site Database (SQL)**. +4. Click **Confirm Rewind**. + +### wp role list + +Return a list of roles + +### wp role reset {ROLE} + +Reset the specified role. You can list multiple roles (without commas) + +``` +wp reset role administrator editor +``` + +wp reset role administrator editorCopyCopied + +You can also replace {ROLE} with `--all` to reset all at once + +## Manage Content + +You can use the following commands to manage your site content, including posts/pages, menus, and media. + +### wp post list + +Return a list of blog posts. + +You can use a variety of flags with this command, including: + +`--format={FORMAT}` + +`--posts_per_page={#}` + +`--post_type={TYPE}` + +Possible post types include `posts`, `pages`, `attachments`, and `products`. + +Multiple flags can be used at once. + +``` +wp post list --post_type=posts,pages --format=count +``` + +wp post list --post\_type=posts,pages --format=countCopyCopied + +### wp post update {POST\_ID} –{KEY}={VALUE} + +Update post information. + +``` +wp post update123 --post_status=draft +``` + +wp post update123 --post\_status=draftCopyCopied + +### wp post delete {POST\_ID} + +Delete a post. + +### wp post exists {POST\_ID} + +Check if a post exists. + +### wp menu list + +List menus on the site. + +### wp menu item list {TERM\_ID} + +List menu items of a specific menu. + +### wp menu item update {MENU\_ITEM\_PARENT\_ID} + +Update a specific menu item. + +The `wp menu` commands can be useful if you see the primary menu freezing in the Customizer or /wp-admin screen. + +### wp media regenerate + +Regenerate media thumbnails when the Jetpack Photon module is deactivated. + +You can use the `--only-missing` flag to skip existing image sizes. + +## Troubleshooting Site Issues + +You can use the following commands when troubleshooting issues on your site. Checking for PHP errors can help you identify sources of errors on your site or use `wp wpcomsh` commands to quickly perform plugin conflict checks or to adjust whether or not you are using managed versions of plugins. + +Both Jetpack and Akismet are managed plugins that are required for your site to work correctly here at WordPress.com. These plugins should remain activated and cannot be switched to unmanaged versions. + +### wp php-errors + +Output error logs in WP-CLI. + +This command only outputs PHP errors, not of any other language such as HTML, Javascript, or CSS. To see these other errors, use the Browser Inspector. + +You can add the `--limit` flag to reduce the number of errors shown to improve readability. + +``` +wp php-errors –limit10 +``` + +wp php-errors –limit10CopyCopied + +### wp wpcomsh deactivate-user-plugins + +Deactivate user plugins. + +You can use the `--interactive` flag to force confirmation for each plugin. + +This command will not deactivate Akismet, Jetpack, or managed ecommerce plugins. + +### wp wpcomsh reactivate-user-plugins + +Reactivate user plugins. + +You can use the `--interactive` flag to to force confirmation for each plugin. + +### wp wpcomsh persistent-data {DATA} + +Return persistent data (which Jetpack uses to verify site capabilities). + +Available DATA options include: + +`WPCOM_PLAN_EXPIRATION` + +`JETPACK_BLOG_TOKEN` + +`WPCOM_PURCHASES` + +`WPCOM_PUBLIC_COMING_SOON` + +### wp wpcomsh plugin use-managed {SLUG} + +Use a managed ([symlinked](https://developer.wordpress.com/docs/guides/symlinked-files-folders/)) version of a plugin. + +This command will remove existing, unmanaged versions and replace them with managed versions. It is available for `amp`, `classic-editor`, `coblocks`, `crowdsignal-forms`, `full-site-editing`, `gutenberg`, `layout-grid`, `page-optimize`, `wp-seo`, `woocommerce`, WooCommerce Extensions from the WordPress.com Marketplace, and [plugins included in the Commerce plan](https://wordpress.com/support/plan-features/entrepreneur-plan/#included-in-the-entrepreneur-plan). + +You can use the `--remove-existing` flag to skip the confirmation step. + +### wp wpcomsh theme use-managed {SLUG} + +Use a managed ([symlinked](https://developer.wordpress.com/docs/guides/symlinked-files-folders/)) version of a theme. + +This command will remove existing, unmanaged versions and replace them with managed versions. It is available for all WordPress.com themes, Storefront, and any Twenty \* themes (ex: Twenty Twenty Two). + +You can use the `--remove-existing` flag to skip the confirmation step. + +### wp wpcomsh plugin use-unmanaged {SLUG} + +Use an unmanaged (not [symlinked](https://developer.wordpress.com/docs/guides/symlinked-files-folders/)) version of a plugin + +This command will remove existing, managed versions and replace them with unmanaged versions from the WordPress.org plugin repository. It will not work for WooCommerce Extensions from the WordPress.com Marketplace and [plugins included in the Commerce plan](https://wordpress.com/support/plan-features/entrepreneur-plan/#included-in-the-entrepreneur-plan). You will need to install these plugins manually to get the unmanaged version. + +You can use the `--remove-existing` flag to skip the confirmation step and the `--version={X.Y.Z}` flag to define the version to install. + +### wp wpcomsh theme use-unmanaged {SLUG} + +Use an unmanaged (not [symlinked](https://developer.wordpress.com/docs/guides/symlinked-files-folders/)) version of a theme. + +This command will remove existing, managed versions and replace them with unmanaged versions from the WordPress.org theme repository if available. + +You can use the `--remove-existing` flag to skip the confirmation step and the `--version={X.Y.Z}` flag to define the version to install. + +The WordPress.com Site Helper or `wpcomsh` must-use plugin runs on sites with activated hosting features to make them work seamlessly in the WordPress.com ecosystem. + +### wp cache flush + +Flush the cache. + +This command is not meant to be a fix for issues and can obscure root causes. Please use with care. Clearing the cache may also make your site run slower while the cache is rebuilt on page load. + +## Skipping Plugins and Themes + +You may want to skip plugins, and sometimes themes, when running CLI commands. This can be useful for troubleshooting conflicts or for overriding restrictions placed by plugins, such as control over roles. + +- `--skip-plugins` can be added before any command and skips plugins +- `--skip-themes` can be added before any command and skips themes + +You can use these commands together. You can also use these commands with slugs to skip specific plugins or themes. This can be useful for ruling out the effects of certain plugins or themes when deactivation is not possible. + +For example: + +``` +wp --skip-plugins=woocommerce, code-snippets, elementor-pro plugin list +``` + +wp --skip-plugins=woocommerce, code-snippets, elementor-pro plugin listCopyCopied diff --git a/content/runtime/documentation/developer-tools/wp-cli/index.md b/content/runtime/documentation/developer-tools/wp-cli/index.md new file mode 100644 index 0000000..bb13ddb --- /dev/null +++ b/content/runtime/documentation/developer-tools/wp-cli/index.md @@ -0,0 +1,37 @@ +--- +type: document +title: WP-CLI +description: "" +resource: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/wp-cli/" +tags: +timestamp: "2026-06-16T19:29:28+00:00" +wordpress: + id: 2513 + status: publish + type: documentation + author: 0 + date: "2026-06-16 19:29:28" + date_gmt: "2026-06-16 19:29:28" + modified: "2026-06-16 19:29:30" + modified_gmt: "2026-06-16 19:29:30" + slug: wp-cli + parent: 2514 + menu_order: 0 + comment_status: closed + ping_status: closed + guid: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/wp-cli/" + comment_count: 0 +--- + +WP-CLI is the command-line interface for WordPress. You can do practically everything in your site’s dashboard with WP-CLI, from updating plugins and themes to creating new user accounts. Also, using WP-CLI gives you access to even more tools, like the ability to clear the WordPress cache or run custom PHP code to debug site issues. + +This feature is available on sites with the [WordPress.com Business or Commerce plan](https://wordpress.com/hosting/?ref=developer-docs#pricing-grid). + +## Next steps + +In the following sections, you can learn more about WP-CLI and how to use it, common commands useful for site management, and some troubleshooting tips. + +- [WP-CLI Overview](https://developer.wordpress.com/docs/developer-tools/wp-cli/overview/) +- [Platform Specific Commands](https://developer.wordpress.com/docs/developer-tools/wp-cli/platform-commands/) +- [Common WP-CLI Commands](https://developer.wordpress.com/docs/developer-tools/wp-cli/common-commands/) +- [Troubleshooting](https://developer.wordpress.com/docs/developer-tools/wp-cli/troubleshooting/) diff --git a/content/runtime/documentation/developer-tools/wp-cli/overview.md b/content/runtime/documentation/developer-tools/wp-cli/overview.md new file mode 100644 index 0000000..55b3625 --- /dev/null +++ b/content/runtime/documentation/developer-tools/wp-cli/overview.md @@ -0,0 +1,55 @@ +--- +type: document +title: WP-CLI overview +description: "" +resource: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/overview/" +tags: +timestamp: "2026-06-16T19:29:23+00:00" +wordpress: + id: 2462 + status: publish + type: documentation + author: 0 + date: "2026-06-16 19:29:23" + date_gmt: "2026-06-16 19:29:23" + modified: "2026-06-16 19:29:29" + modified_gmt: "2026-06-16 19:29:29" + slug: overview + parent: 2513 + menu_order: 0 + comment_status: closed + ping_status: closed + guid: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/overview/" + comment_count: 0 +--- + +WP-CLI is a command-line interface for WordPress. It provides developers comfortable with the terminal tools to manage a WordPress site from the command line. WP-CLI is useful for everything from site administration to debugging site issues. + +## Access WP-CLI + +WP-CLI comes preinstalled on WordPress.com and extends the shell to provide WordPress-specific command line tools. You can start running WP-CLI commands once you have connected to your site via SSH. + +Visit the [SSH guide to learn how to activate and use SSH](https://wordpress.com/support/ssh/). + +## Using WP-CLI + +Once you have SSH access to your WordPress.com account, you run WP-CLI commands as you would normally. + +``` +wp post list + ++----+--------------+-------------+---------------------+-------------+ +| ID | post_title | post_name | post_date | post_status | ++----+--------------+-------------+---------------------+-------------+ +| 1 | Hello world! | hello-world | 2025-01-04 14:07:11 | publish | ++----+--------------+-------------+---------------------+-------------+ +``` + +wp post list +----+--------------+-------------+---------------------+-------------+ | ID | post\_title | post\_name | post\_date | post\_status | +----+--------------+-------------+---------------------+-------------+ | 1 | Hello world! | hello-world | 2025-01-04 14:07:11 | publish | +----+--------------+-------------+---------------------+-------------+ + +## Additional WP-CLI Resources + +WP-CLI is available as a stand-alone install for local development environments. Many popular plugins for WordPress also extend WP-CLI to provide command-line tools for their features. Below is a list of additional WP-CLI resources that are handy to bookmark. + +- [WP-CLI home page on WordPress.org](http://wordpress.org)[WordPress.org WP-CLI documentation](https://developer.wordpress.org/cli/commands/) +- [WooCommerce WP-CLI documentation](https://github.com/woocommerce/woocommerce/wiki/WC-CLI-Overview) diff --git a/content/runtime/documentation/developer-tools/wp-cli/platform-commands.md b/content/runtime/documentation/developer-tools/wp-cli/platform-commands.md new file mode 100644 index 0000000..404ce7d --- /dev/null +++ b/content/runtime/documentation/developer-tools/wp-cli/platform-commands.md @@ -0,0 +1,112 @@ +--- +type: document +title: Platform-specific commands +description: "" +resource: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/platform-commands/" +tags: +timestamp: "2026-06-16T19:29:23+00:00" +wordpress: + id: 2461 + status: publish + type: documentation + author: 0 + date: "2026-06-16 19:29:23" + date_gmt: "2026-06-16 19:29:23" + modified: "2026-06-16 19:29:29" + modified_gmt: "2026-06-16 19:29:29" + slug: platform-commands + parent: 2513 + menu_order: 0 + comment_status: closed + ping_status: closed + guid: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/platform-commands/" + comment_count: 0 +--- + +While the majority of the core WP-CLI commands are available to you, there are also some additional commands that are exclusive to WordPress.com hosting. These allow you to interact with and control specific elements of your [WordPress.com Business or Commerce plan](https://wordpress.com/hosting/?ref=developer-docs#pricing-grid). + +To see which commands are available on your plan, you can use the WP-CLI `--help` flag in the terminal: + +``` +wp --help +``` + +wp --help + +## Business plan + +### atomic + +Control aspects of your WordPress.com hosting plan. + +### custom-fonts + +Manage the Custom Fonts plugin. + +### dereferenced + +Helper utilities for working with dereferenced (development mode) sites. + +### disk-usage + +Output disk usage information for the document root and tmp directories. + +### edge-cache + +Edge Cache control – query and control the Edge Cache. + +### jetpack + +Control your local [Jetpack installation through WP-CLI](https://jetpack.com/support/jetpack-cli/). + +### jetpack-heartbeat + +Interact with the Jetpack Heartbeat. + +### jetpack-waf + +Control the [Jetpack Web Application Firewall](https://jetpack.com/support/jetpack-waf/). + +### launch-site + +Makes the site live to the public. + +### php-errors + +Output contents of php-errors. + +### wpcomsh + +WordPress.com specific commands. + +## Commerce plan + +If you use the Commerce plan, there are also specific commands related to the Commerce tools installed on your site. + +### action-scheduler + +Commands for Action Scheduler. + +### akismet + +Filter and monitor spam comments. + +### mailpoet + +WP-CLI commands to manage aspects of MailPoet. + +### videopress + +VideoPress command line utilities. + +### wc + +WP-CLI commands to manage [your WooCommerce store](https://developer.woocommerce.com/docs/woocommerce-cli-commands/). + +## Allowed Commands + +Certain core WP-CLI commands are unavailable on WordPress.com Business or Commerce plans to provide a secure and performant hosting environment. If a command is disabled, it will return forbidden when you try to run it. + +Typically, you can do anything on CLI that you could do with the GUI (Graphical User Interface) in your site’s dashboard, but without any of the warnings or checks provided in the GUI. Disabling certain commands makes it harder to damage a site irreparably or destroy it accidentally. + +To see which commands are available on your plan, use the WP-CLI `--help` flag in the terminal. diff --git a/content/runtime/documentation/developer-tools/wp-cli/troubleshooting.md b/content/runtime/documentation/developer-tools/wp-cli/troubleshooting.md new file mode 100644 index 0000000..c3a39fc --- /dev/null +++ b/content/runtime/documentation/developer-tools/wp-cli/troubleshooting.md @@ -0,0 +1,36 @@ +--- +type: document +title: Troubleshooting +description: "" +resource: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/troubleshooting/" +tags: +timestamp: "2026-06-16T19:29:22+00:00" +wordpress: + id: 2459 + status: publish + type: documentation + author: 0 + date: "2026-06-16 19:29:22" + date_gmt: "2026-06-16 19:29:22" + modified: "2026-06-16 19:29:29" + modified_gmt: "2026-06-16 19:29:29" + slug: troubleshooting + parent: 2513 + menu_order: 0 + comment_status: closed + ping_status: closed + guid: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/troubleshooting/" + comment_count: 0 +--- + +## HTML output + +Occasionally, you may see HTML returned when you enter a command in the CLI. This can happen when you have a maintenance plugin active or can be a sign that a theme or plugin is coded incorrectly. + +If no maintenance plugin is present, you can use the `--skip-*` flag to verify whether the source is a plugin or theme. Once identified, you can deactivate the plugin or theme and may want to reach out to the plugin developer to get it corrected. + +## Allowed commands + +Specific WP-CLI commands by return forbidden when you try to run them. This is because they are not on the list of Allowed commands on WordPress.com plans. + +WP-CLI SupportDue to the complex nature of WP-CLI commands, we are not able to provide extensive support for using these tools. [Happiness Engineers are available to help with issues accessing WP-CLI](https://developer.wordpress.com/docs/glance/support/) but cannot guide you through using commands. diff --git a/content/runtime/documentation/elasticsearch/elasticsearch-queries.md b/content/runtime/documentation/elasticsearch/elasticsearch-queries.md new file mode 100644 index 0000000..f24dcec --- /dev/null +++ b/content/runtime/documentation/elasticsearch/elasticsearch-queries.md @@ -0,0 +1,130 @@ +--- +type: document +title: Elasticsearch queries +description: "" +resource: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/elasticsearch-queries/" +tags: +timestamp: "2026-06-16T19:29:28+00:00" +wordpress: + id: 2511 + status: publish + type: documentation + author: 0 + date: "2026-06-16 19:29:28" + date_gmt: "2026-06-16 19:29:28" + modified: "2026-06-16 19:29:30" + modified_gmt: "2026-06-16 19:29:30" + slug: elasticsearch-queries + parent: 2512 + menu_order: 0 + comment_status: closed + ping_status: closed + guid: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/elasticsearch-queries/" + comment_count: 0 +--- + +There are slightly different limitations on the query APIs depending on which tier of service you have (WordPress VIP, Jetpack Pro, or Jetpack Related Posts). Depending on the level of service different features of the Elasticsearch Query DSL are available. There are currently two APIs available: + +- [Post Search API](https://developer.wordpress.com/docs/api/1.1/post/sites/%24site/search/) (VIP and Jetpack Pro). + - Mostly a wrapper around the [Elasticsearch /\_search API](https://www.elastic.co/guide/en/elasticsearch/reference/2.4/search-request-body.html). + - The response looks slightly different due to filtering out some fields and some historical reasons. + - Supports a subset of the top query parameters. See [API docs](https://developer.wordpress.com/docs/api/1.1/post/sites/%24site/search/). +- [Related Posts API](https://developer.wordpress.com/docs/api/1.1/post/sites/%24site/posts/%24post/related/) (Free) + - Accepts Elasticsearch Filters for modifying the results. Many common examples [here](https://jetpack.com/support/related-posts/customize-related-posts/). + - Returns the post\_id and blog\_id of any results. + +## Allowed Queries (& Filters) + +To avoid performance problems and ensure backwards compatibility we only allow a subset of the[ Elasticsearch Query DSL](https://www.elastic.co/guide/en/elasticsearch/reference/2.4/query-dsl.html). + +Elasticsearch has moved away from [explicitly separating queries and filters](https://www.elastic.co/guide/en/elasticsearch/reference/2.4/query-filter-context.html), so we don’t either. + +### Common Queries: + +- [bool](http://www.elasticsearch.org/guide/en/elasticsearch/reference/2.4/query-dsl-bool-query.html) +- [match](http://www.elasticsearch.org/guide/en/elasticsearch/reference/2.4/query-dsl-match-query.html) +- [multi match](http://www.elasticsearch.org/guide/en/elasticsearch/reference/2.4/query-dsl-multi-match-query.html) +- [function score](http://www.elasticsearch.org/guide/en/elasticsearch/reference/2.4/query-dsl-function-score-query.html) + - random\_score is not supported +- [match all](http://www.elasticsearch.org/guide/en/elasticsearch/reference/2.4/query-dsl-match-all-query.html) +- [range](https://www.elastic.co/guide/en/elasticsearch/reference/2.4/query-dsl-range-query.html) +- [term](https://www.elastic.co/guide/en/elasticsearch/reference/2.4/query-dsl-term-query.html) +- [terms](https://www.elastic.co/guide/en/elasticsearch/reference/2.4/query-dsl-terms-query.html) + +### Exotic Queries: + +- [constant score](http://www.elasticsearch.org/guide/en/elasticsearch/reference/2.4/query-dsl-constant-score-query.html) +- [boosting](http://www.elasticsearch.org/guide/en/elasticsearch/reference/2.4/query-dsl-boosting-query.html) +- [dis max](http://www.elasticsearch.org/guide/en/elasticsearch/reference/2.4/query-dsl-dis-max-query.html) +- [more like this / mlt](http://www.elasticsearch.org/guide/en/elasticsearch/reference/2.4/query-dsl-mlt-query.html) +- [more like this field / mlt field](http://www.elasticsearch.org/guide/en/elasticsearch/reference/2.4/query-dsl-mlt-field-query.html) +- [geo bounding box](https://www.elastic.co/guide/en/elasticsearch/reference/2.4/query-dsl-geo-bounding-box-query.html) +- [geo distance](http://www.elasticsearch.org/guide/en/elasticsearch/reference/2.4/query-dsl-geo-distance-query.html) +- [geo distance range](http://www.elasticsearch.org/guide/en/elasticsearch/reference/2.4/query-dsl-geo-distance-range-query.html) +- [geohash cell](http://www.elasticsearch.org/guide/en/elasticsearch/reference/2.4/query-dsl-geohash-cell-query.html) +- [exists](https://www.elastic.co/guide/en/elasticsearch/reference/2.4/query-dsl-exists-query.html) + +### Deprecated Queries (Will be removed in the future): + +- [and filter](http://www.elasticsearch.org/guide/en/elasticsearch/reference/2.4/query-dsl-and-filter.html) (deprecated, use bool) +- [not filter](http://www.elasticsearch.org/guide/en/elasticsearch/reference/2.4/query-dsl-not-filter.html) (deprecated, use bool) +- [or filter](http://www.elasticsearch.org/guide/en/elasticsearch/reference/2.4/query-dsl-or-filter.html) (deprecated, use bool) +- [filtered query](http://www.elasticsearch.org/guide/en/elasticsearch/reference/2.4/query-dsl-filtered-query.html) (deprecated, use bool) + +## Allowed Aggregations + +To avoid performance problems and ensure backwards compatibility we only allow a subset of the[ Elasticsearch Aggregations DSL](https://www.elastic.co/guide/en/elasticsearch/reference/2.4/search-aggregations.html). We do not currently allow any pipeline aggregations. + +Aggregations are not allowed on any analyzed content fields (eg “content”, “title”, “tag.name.en”). + +### Metric Aggregations + +- [Extended Stats](https://www.elastic.co/guide/en/elasticsearch/reference/2.4/search-aggregations-metrics-extendedstats-aggregation.html) +- [Stats](https://www.elastic.co/guide/en/elasticsearch/reference/2.4/search-aggregations-metrics-stats-aggregation.html) + +### Bucket Aggregations + +- [Date Histogram](https://www.elastic.co/guide/en/elasticsearch/reference/2.4/search-aggregations-metrics-sum-aggregation.html) +- [Filters](https://www.elastic.co/guide/en/elasticsearch/reference/2.4/search-aggregations-bucket-filters-aggregation.html) +- [Histogram](https://www.elastic.co/guide/en/elasticsearch/reference/2.4/search-aggregations-bucket-histogram-aggregation.html) +- [Terms](https://www.elastic.co/guide/en/elasticsearch/reference/2.4/search-aggregations-bucket-terms-aggregation.html) + +## Size Field + +The allowed maximum **size** depends on your level of service: + +- Jetpack Professional Plan: 0-100 +- WordPress VIP (with a dedicated index): 0-1000 +- Jetpack Free Plan (Related Posts API): 1-15 + +## From Field + +The allowed maximum **from** depends on your level of service: + +- Jetpack Professional Plan: 0-1000 +- WordPress VIP (with a dedicated index): 0-9000 +- Jetpack Free Plan (Related Posts API): 0-50 + +## Fields + +Although it is possible to return fields from the index, this is highly discouraged for production queries. The index has been optimized to efficiently and quickly return **post\_id** and **blog\_id**. Returning other fields is possible, but will slow down search results. + +The other reason for relying on **post\_id** and then getting the final data from the DB is that the Elasticsearch index is only a mirror of your data. It is cached, can be delayed, or can be slightly out of sync with your database. Any of these could result in serving stale content if you rely on it. + +## Sorting + +Basic [sorting](https://www.elastic.co/guide/en/elasticsearch/reference/2.4/search-request-sort.html) on any field is allowed. We don’t allow any scripting. + +## Allowed Suggestions (Experimental) + +Suggestions are currently experimental as we don’t yet have any libraries using it in production. There is an [open issue](https://github.com/Automattic/jetpack/issues/7924) for how to integrate it. Only term and phrase suggestions are supported. Exact support may change. + +## Allowed Rescoring (Experimental) + +We currently support rescoring of queries for some experimental features. You probably shouldn’t use it. + +## Facets (Deprecated) + +Facets are deprecated and will be removed. Do not use them. Use aggregations instead. We still have some VIP clients using them which is why the API accepts them, but they probably won’t work for you. + +*\* Elasticsearch is a trademark of Elasticsearch BV, registered in the U.S. and in other countries.* diff --git a/content/runtime/documentation/elasticsearch/index.md b/content/runtime/documentation/elasticsearch/index.md new file mode 100644 index 0000000..ecf2564 --- /dev/null +++ b/content/runtime/documentation/elasticsearch/index.md @@ -0,0 +1,69 @@ +--- +type: document +title: Elasticsearch-powered APIs +description: "" +resource: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/elasticsearch/" +tags: +timestamp: "2026-06-16T19:29:28+00:00" +wordpress: + id: 2512 + status: publish + type: documentation + author: 0 + date: "2026-06-16 19:29:28" + date_gmt: "2026-06-16 19:29:28" + modified: "2026-06-16 19:29:28" + modified_gmt: "2026-06-16 19:29:28" + slug: elasticsearch + parent: 0 + menu_order: 0 + comment_status: closed + ping_status: closed + guid: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/elasticsearch/" + comment_count: 0 +--- + +We maintain [Elasticsearch](https://www.elastic.co/products/elasticsearch) indices for all posts on WordPress.com and all posts synced through the [Jetpack plugin](https://jetpack.com/). + +These documents describe the index structures and APIs that are available for querying. These APIs power features that are available on [WordPress VIP](https://vip.wordpress.com/documentation/vip-go/elasticsearch-on-vip-go/)and in the [Jetpack Professional Plan](https://cloud.jetpack.com/pricing). The [Jetpack Related Posts API](https://developer.wordpress.com/docs/api/1.1/post/sites/%24site/posts/%24post/related/)also accepts Elasticsearch filters. + +## API Availability + +There are three tiers of availability: + +- **WordPress VIP**: We can build a single index for your content (setup fee required). The code for building the index is [open source](https://github.com/Automattic/wpes-lib/blob/master/src/indices/vip2-all-posts-index.php). Often experimental features/fields or things we cannot scale to all sites will get implemented here first. +- [**Jetpack Professional Plan**](https://cloud.jetpack.com/pricing): All Jetpack Pro sites (including all VIP sites) are indexed into our global Elasticsearch cluster and can be queried with Elasticsearch Query API calls. We do not support the entire ES Query DSL, but do support most of it. +- **Jetpack Free Plan**: All sites are indexed to power the [Related Posts API](https://jetpack.com/support/related-posts/). The API accepts custom [Elasticsearch filters](https://developer.wordpress.com/docs/api/1.1/post/sites/%24site/posts/%24post/related/). + +## Elasticsearch Versions and Backwards Compatibility + +The Elasticsearch project is focused on continually improving its APIs and so regularly breaks backwards compatibility. Our APIs strive to maintain backwards compatibility and so there are a number of features that we choose not to support for various security or performance reasons. For example, all scripting is disabled in our API. We also do not try and use the very latest version of Elasticsearch because we are committed to backwards compatibility. + +Our [query API](https://developer.wordpress.com/docs/api/1.1/post/sites/%24site/search/) looks mostly like the Elasticsearch Search API from [version 2.4 of Elasticsearch](https://www.elastic.co/guide/en/elasticsearch/reference/2.4/search-request-body.html). We do however accept some deprecated features and perform some query rewriting to maintain compatibility. A good example is when we moved from ES 1.x to 2.x all content had to be migrated from being stored in the “content” field with multiple analyzers to being stored in a separate field for each language analyzer: “content.en”, “content.fr”, “content.default”, etc. We rewrite queries that still use the “content” field. + +## Existing Libraries + +There likely will be times where we have to **break backwards compatibility** (in hopefully minor ways). The best way to ensure your application will not run into these issues is to use one of the existing libraries or filters rather than writing a completely custom search query: + +- Jetpack Related Posts [filter hooks](https://developer.jetpack.com/?search_for=wpapi-hook&s=jetpack_related) and [examples](https://jetpack.com/support/customize-related-posts/). +- Jetpack Search [filter hooks](https://developer.jetpack.com/?search_for=wpapi-hook&s=jetpack_search) +- [Jetpack Search Search Query Builder](https://github.com/Automattic/jetpack/blob/master/_inc/lib/jetpack-wpes-query-builder/jetpack-wpes-query-parser.php) (abstraction layer) +- [Jetpack Search Query Builder](https://github.com/Automattic/jetpack/blob/master/_inc/lib/jetpack-wpes-query-builder/jetpack-wpes-query-builder.php) (abstraction layer) +- [es-wp-query](https://github.com/alleyinteractive/es-wp-query) (converts WP\_Query MySQL queries to Elasticsearch queries). Fully supported on VIP Indices, may partially work on Jetpack Pro but it is untested. +- [es-admin](https://github.com/alleyinteractive/es-admin) (power the wp-admin post search with ES). Fully supported on VIP indices, unknown on Jetpack Pro. + +Because code makes the best documentation, how the mappings and documents are built for our indices is mostly available in [WPES-Lib](https://github.com/Automattic/wpes-lib/). [Data.blog](https://data.blog/) has the best description of [how our real time indexing](http://data.blog/2017/07/11/real-time-elasticsearch-indexing-on-wordpress-com/) works. + +## Documents + +We index all WordPress posts, pages, and custom post types as long as the post status is one of `publish`, `trash`, `pending`, `draft`, `future`, or `private`. Posts which are publicly available can be queried from our API unauthenticated. Authenticated requests will return all posts. In the case of Jetpack, any posts which are blocked from syncing will not be available in our index. + +See the [post document schema](https://developer.wordpress.com/elasticsearch-post-doc-schema-v2/) for details on all fields in the index. + +## Search API + +There are slightly different limitations on the APIs depending on which tier of service you have (WordPress VIP, Jetpack Pro, or Jetpack Related Posts). Depending on the level of service different features of the Elasticsearch Query DSL are available. + +See [the query API](https://developer.wordpress.com/docs/elasticsearch/elasticsearch-queries/) for details and limitations of available queries, filters, and aggregations. + +*\* Elasticsearch is a trademark of Elasticsearch BV, registered in the U.S. and in other countries.* diff --git a/content/runtime/documentation/firehose.md b/content/runtime/documentation/firehose.md new file mode 100644 index 0000000..183cc3a --- /dev/null +++ b/content/runtime/documentation/firehose.md @@ -0,0 +1,75 @@ +--- +type: document +title: WordPress.com Firehose +description: "" +resource: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/firehose/" +tags: +timestamp: "2026-06-16T19:29:26+00:00" +wordpress: + id: 2488 + status: publish + type: documentation + author: 0 + date: "2026-06-16 19:29:26" + date_gmt: "2026-06-16 19:29:26" + modified: "2026-06-16 19:29:26" + modified_gmt: "2026-06-16 19:29:26" + slug: firehose + parent: 0 + menu_order: 0 + comment_status: closed + ping_status: closed + guid: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/firehose/" + comment_count: 0 +--- + +WordPress publishers and visitors produce [thousands of new posts and comments every hour](https://wordpress.com/stats/posting/). These content streams are available in three real-time formats from redundant servers. These streams are intended for partners like search engines, artificial intelligence (AI) products and market intelligence providers who would like to ingest a real-time stream of new content from a wide spectrum of publishers. + +## Feeds + +- **Posts Firehose:** the Posts Firehose is a stream of posts—averaging 1 million/day—from the tens of millions of websites published on WordPress.com. Posts are also available for Jetpack-powered WordPress(.org) sites, through a separate feed. +- **Comments Firehose:** the Comments Firehose streams hundreds of thousands of comments every day from WordPress.com. Comments are also available for Jetpack-powered WordPress(.org) sites, through a separate feed. +- **Likes Firehose:** the Likes Firehose streams engagement data from WordPress.com’s [“like” feature](https://wordpress.com/support/likes/). + +## Feed Formats + +- **PubSub:** An extension of the popular Jabber/[XMPP](https://xmpp.org/) instant messaging protocol. WordPress.com operates a Jabber service at [im.wordpress.com](https://im.wordpress.com/) that allows all WordPress.com users to subscribe to the blogs of their choice and receive instant notification of new items. However, the full streams are access-controlled. +- **JSON Stream:** A stream of JSON formatted data delivered over HTTP. You can view a very limited sample stream by using `curl` in a terminal: + - Posts: `curl xmpp.wordpress.com:8008/posts.json` + - Comments: `curl xmpp.wordpress.com:8008/comments.json` +- **XML Stream:** Delivers the same pubsub-style XML streams by the much simpler mechanism of an HTTP GET request. This makes implementing the streams as simple as can be. You can view a very limited sample stream by using `curl` in a terminal: + - Posts: `curl xmpp.wordpress.com:8008/firehose.xml` + - Comments: `curl xmpp.wordpress.com:8008/gusher.xml` + +## Firehose Terms of Service + +By using Firehose or accessing Firehose data, you agree to these terms and all other operating rules, policies, and procedures that may be published from time to time by Automattic (collectively, the “Agreement”). This Agreement contains, among other things, warranty disclaimers, and liability limitations. + +**Permitted Uses.** You may use Firehose to search, display, analyze, retrieve, and view the data provided to you through the Firehose. You may also use the WordPress.com name or logos and other brand elements that Automattic makes available in order to identify the source of the information, provided the use doesn’t suggest any endorsement by Automattic. You agree to comply with all applicable privacy laws and regulations, and will post and adhere to a privacy policy that does not modify, supersede, or be inconsistent with the [Automattic Privacy Policy](https://automattic.com/privacy/). + +**Prohibited Uses.** If you use Firehose, you agree not to: + +- Engage in, encourage, or facilitate activity that is malicious or illegal under applicable law. +- Interfere with, disrupt, or attack any service or network, including Automattic’s. +- Republish the content, provide any third parties with access to Firehose or Firehose data, or enable any third parties to distribute Firehose data. +- Substantially replicate products or services offered by Automattic, or create a competing service, such as by creating a separate publishing platform. +- Display, distribute, or otherwise make available content or data to governmental entities for intelligence gathering or surveillance purposes. +- Use the information in a biased, misleading, or dishonest manner, for example, to promote or publicize a biased political point of view. +- Modify, decompile, reverse engineer, or otherwise alter or seek to derive the trade secrets and other inherent intellectual property of the Automattic APIs. +- Use the Firehose or Firehose Data to (i) to create or enable any app, website, tool, or other mechanism that is, or enables, or operates in conjunction with, any malware, spyware, adware, other malicious programs or code, or (ii) in any manner that would violate any applicable law or governmental regulation. +- Cache or store personal data or user passwords. +- Use Firehose content or data to profile, or create profiles of, individuals, or directly target individuals with advertisements or other messages. + +**Suspension.** If Automattic believes, in its sole discretion, that you have violated or attempted to violate this Agreement, your ability to use and access Firehose may be temporarily or permanently revoked, with or without notice. + +**Account.** You will be solely responsible and liable for any activity that occurs under your account. You are responsible for keeping your login and password secure. + +**No Warranties.** Automattic makes no, and expressly disclaims any, representations or warranties, whether express or implied, regarding Firehose or the content provided via Firehose. This disclaimer includes disclaimer of warranties of fitness for a particular purpose, non infringement, and that its products will be uninterrupted or error-free. + +**Intellectual Property.** This Agreement does not transfer from Automattic to you any Automattic or third party intellectual property, and all right, title, and interest in and to such property will remain (as between the parties) solely with Automattic. During the term of this Agreement, and subject to the terms and conditions herein, Automattic grants you a limited, non-exclusive, non-transferable license to access and use Firehose data. + +**Liability.** In no event will Automattic be liable with respect to any subject matter of this Agreement under any contract, negligence, strict liability, or other legal or equitable theory for: (i) the cost of procurement for substitute products or services; (ii) interruption of use or loss or corruption of data; or (iii) for any amounts that exceed the fees paid by you to Automattic under this Agreement during the twelve (12) month period prior to the cause of action. Neither party shall be liable under this Agreement for any incidental or consequential damages. + +**Changes.** We may make modifications to the Firehose service that do not materially degrade your level of service. We may also make changes to the pricing or other terms under which we offer the service. If we make changes that are material, we will let you know by sending you an email or other communication before the changes take effect, which shall be no earlier than the next Renewal Period. Your continued use of the Service will be subject to the new terms. + +**Jurisdiction and Applicable Law.** This Agreement and any access to or use of the Service will be governed by the laws of the state of California, excluding its conflict of law provisions. The venue for any disputes arising out of or relating to this Agreement or the Service will be the state and federal courts located in San Francisco County, California. diff --git a/content/runtime/documentation/get-started/create-site.md b/content/runtime/documentation/get-started/create-site.md new file mode 100644 index 0000000..e8cab29 --- /dev/null +++ b/content/runtime/documentation/get-started/create-site.md @@ -0,0 +1,55 @@ +--- +type: document +title: "Step 1: Create a site" +description: "" +resource: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/create-site/" +tags: +timestamp: "2026-06-16T19:29:24+00:00" +wordpress: + id: 2472 + status: publish + type: documentation + author: 0 + date: "2026-06-16 19:29:24" + date_gmt: "2026-06-16 19:29:24" + modified: "2026-06-16 19:29:30" + modified_gmt: "2026-06-16 19:29:30" + slug: create-site + parent: 2510 + menu_order: 0 + comment_status: closed + ping_status: closed + guid: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/create-site/" + comment_count: 0 +--- + +You’ll need a website on WordPress.com where you’ll be able to sync your local development work. + +## Create a new site + +To take full advantage of the developer tools we have available on WordPress.com, like GitHub deployments, Studio Sync, WP-CLI access, and staging sites, you’ll need a [Business or Commerce plan](https://wordpress.com/hosting/?ref=developer-docs#pricing-grid). + +[Sign up for WordPress.com](https://wordpress.com/hosting/?ref=developer-docs#pricing-grid) + +## Create multiple sites + +If you have 3+ sites, plugins, and/or themes you’re managing, you may want to check out [Automattic for Agencies](https://wordpress.com/for-agencies/?ref=developer-docs), our agency program. By being a part of this program, you get: + +- Agency pricing on hosting plans, tools, and plugins. +- Referral earnings. +- Premier support. +- Custom cart capabilities for clients. + +You can purchase WordPress.com hosting plans through Automattic for Agencies at a discount if you’re purchasing five or more plans. You may also import existing WordPress sites to sites created through Automattic for Agencies. + +[Sign up for Automattic for Agencies](https://wordpress.com/for-agencies/?ref=developer-docs) + +## Migrate to WordPress.com + +If you already have a WordPress site that you’d like to migrate to WordPress.com, the process is simple and straightforward. Simply add your site URL [here](https://wordpress.com/move/) and follow the prompts. + +[Start a migration](https://wordpress.com/move/) + +## Next steps + +Once you have a production site on WordPress.com, you may choose to [create a staging site](https://wordpress.com/support/how-to-create-a-staging-site/#how-to-create-a-staging-site) if you’d prefer to deploy to a staging environment over a production environment. Then, set up your [local environment](https://developer.wordpress.com/docs/get-started/local-environment-setup/) if you haven’t already done so. diff --git a/content/runtime/documentation/get-started/deploy.md b/content/runtime/documentation/get-started/deploy.md new file mode 100644 index 0000000..6001032 --- /dev/null +++ b/content/runtime/documentation/get-started/deploy.md @@ -0,0 +1,54 @@ +--- +type: document +title: "Step 5: Deploy to your production or staging site" +description: "" +resource: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/deploy/" +tags: +timestamp: "2026-06-16T19:29:24+00:00" +wordpress: + id: 2468 + status: publish + type: documentation + author: 0 + date: "2026-06-16 19:29:24" + date_gmt: "2026-06-16 19:29:24" + modified: "2026-06-16 19:29:29" + modified_gmt: "2026-06-16 19:29:29" + slug: deploy + parent: 2510 + menu_order: 0 + comment_status: closed + ping_status: closed + guid: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/deploy/" + comment_count: 0 +--- + +WordPress.com’s [GitHub Deployments](https://wordpress.com/support/github-deployments/) feature makes it easy to deploy changes from GitHub to your production or staging site. + +You can set up GitHub Deployments on your production or staging site by: + +1. [Connecting the plugin, theme, or site repository](https://wordpress.com/support/github-deployments/#authorize-install). +2. [Setting up the deployment](https://wordpress.com/support/github-deployments/#manage-deployment-settings). +3. [Optionally setting up workflows under Advanced Deployment](https://wordpress.com/support/github-deployments/#advanced-deployment). + +You must trigger the first deployment, [either automatically or manually](https://wordpress.com/support/github-deployments/#deploy). If you’re syncing a theme or plugin, you may need to activate it on the Plugins or Themes page in wp-admin. + +If you set up automatic deployments through GitHub Deployments, any additional changes to the main branch in your GitHub repository will be automatically synced with your production or staging site. + +If you set up manual deployments, syncs will need to be [manually triggered](https://wordpress.com/support/github-deployments/#deploy) through your GitHub Deployments dashboard. + +For convenience and maximum control over your production site, we recommend setting up: + +- Manual deployments for production sites. +- Automatic deployments for staging sites. + +If you decide to use a staging site, you can [synchronize your staging site to your production site](https://wordpress.com/support/how-to-create-a-staging-site/#staging-to-production). + +## Next steps + +Setting up a local-to-production development flow is only the start of what you can do on WordPress.com. Be sure to check out our documentation for: + +- [Documentation Tools](https://developer.wordpress.com/docs/developer-tools/) +- [Site Performance](https://developer.wordpress.com/docs/site-performance/) +- [Platform Features](https://developer.wordpress.com/docs/platform-features/) +- [Troubleshooting](https://developer.wordpress.com/docs/troubleshooting/) diff --git a/content/runtime/documentation/get-started/develop-locally.md b/content/runtime/documentation/get-started/develop-locally.md new file mode 100644 index 0000000..0f0f2e6 --- /dev/null +++ b/content/runtime/documentation/get-started/develop-locally.md @@ -0,0 +1,42 @@ +--- +type: document +title: "Step 4: Develop locally" +description: "" +resource: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/develop-locally/" +tags: +timestamp: "2026-06-16T19:29:24+00:00" +wordpress: + id: 2469 + status: publish + type: documentation + author: 0 + date: "2026-06-16 19:29:24" + date_gmt: "2026-06-16 19:29:24" + modified: "2026-06-16 19:29:29" + modified_gmt: "2026-06-16 19:29:29" + slug: develop-locally + parent: 2510 + menu_order: 0 + comment_status: closed + ping_status: closed + guid: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/develop-locally/" + comment_count: 0 +--- + +[WordPress Studio](https://developer.wordpress.com/studio/?ref=developer-docs) provides convenient quick-access buttons for opening your site, plugin, and theme code directly in popular code editors like [Visual Studio Code](https://code.visualstudio.com/) and [PhpStorm](https://www.jetbrains.com/phpstorm/). + +As you develop, you’ll see any file changes within the folder where you initialized a local repository appear in the “changed files” area within GitHub Desktop. + +![A screenshot depicting changes in the GitHub Desktop app.](https://developer.wordpress.com/wp-content/uploads/2024/11/github-desktop-wordpress-development-hello-dolly.jpg)Depending on your workflow, you may decide to commit your changes to [different branches](https://docs.github.com/en/desktop/making-changes-in-a-branch/managing-branches-in-github-desktop#creating-a-branch) that you merge into your main branch. If you’ve been working on the main branch, and you decide to create a new branch, be sure to click the “**Bring my changes to new-branch-name**” option before clicking the “**Switch Branch**” button. + +![A screenshot depicting the switch branch modal in GitHub Desktop.](https://developer.wordpress.com/wp-content/uploads/2024/11/switch-branch-github-desktop.jpg)Once you’re on the correct branch: + +1. Give your commit a summary, and then click the “**Commit to new-branch name**” button. +2. Click “**Publish Branch**“. +3. Click the “**Preview Pull Request”** button, and then the **“Create Pull Request”** button. +4. Once you’re taken to GitHub in your browser, click the **“Create Pull Request”** button. It’s here that you can set up [rulesets](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets), [actions](https://github.com/features/actions), and/or [apps](https://github.com/marketplace/category/continuous-integration) to run prior to being able to merge any code into your main branch. You may also invite contributors, request code reviewers, and categorize the change. +5. Once you’re ready to merge the pull request to your main branch, click the “**Merge pull request”** button, and then **“Confirm merge”** button. + +As a best practice and to keep your repository tidy, delete the branch by clicking the **“Delete branch”** button. + +After merging your changes, the next step is to deploy them to your WordPress.com production or staging site using the [GitHub Deployments](https://developer.wordpress.com/docs/get-started/deploy/) feature. diff --git a/content/runtime/documentation/get-started/github.md b/content/runtime/documentation/get-started/github.md new file mode 100644 index 0000000..3ba15a6 --- /dev/null +++ b/content/runtime/documentation/get-started/github.md @@ -0,0 +1,114 @@ +--- +type: document +title: "Step 3: Set up GitHub" +description: "" +resource: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/github/" +tags: +timestamp: "2026-06-16T19:29:24+00:00" +wordpress: + id: 2470 + status: publish + type: documentation + author: 0 + date: "2026-06-16 19:29:24" + date_gmt: "2026-06-16 19:29:24" + modified: "2026-06-16 19:29:30" + modified_gmt: "2026-06-16 19:29:30" + slug: github + parent: 2510 + menu_order: 0 + comment_status: closed + ping_status: closed + guid: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/github/" + comment_count: 0 +--- + +We recommend creating a GitHub repository for each project you’re working on—a theme, a plugin, or a full site. You can [create a free GitHub account](https://github.com/signup?source=header-home) and then set up as many public or private repositories as you like. GitHub will give you the flexibility of version control and can [effortlessly sync with your WordPress.com production or staging site](https://developer.wordpress.com/docs/get-started/deploy/). + +This development workflow is recommended for most use cases, but an alternative option is [Studio Sync](https://developer.wordpress.com/docs/developer-tools/studio/sync/). This feature allows you to synchronize a complete WordPress.com site with a local WordPress Studio site in either direction without requiring GitHub. Studio Sync can also [complement GitHub-based development workflows](https://wordpress.com/blog/2025/03/19/local-wordpress-development-workflows/) for added flexibility. + +There are many ways to add your code to a GitHub repository, like using the command line. However, we recommend using [GitHub Desktop](https://desktop.github.com/download/), a free app that serves as a GUI for your commits and pull requests. It allows you to seamlessly interact with your local site files and GitHub repositories through an intuitive visual interface. + +The tutorials below will cover this workflow. + +[Download GitHub Desktop](https://desktop.github.com/download/) + +## If you’re working on a new theme + +First, you’ll need to create a local repository inside of your theme folder: + +1. In GitHub Desktop, click the “**Create a New Repository on your Local Drive…**” button or navigate to *File > New Repository*. +2. In the “**Repository Name**” field, type the name of the theme you’re developing. It should match the name of the theme in your `wp-content/themes/` folder. +3. In the “**Local Path**” field, select the `wp-content/themes/` folder in your Studio site (the path will look something like this: `/Users/user_name/Studio/site_name/wp-content/themes`). +4. Click **“Create Repository**“. + +Once you click the “**Create Repository”** button, you will have created a local repository. Two hidden files will be added to your individual theme folder (`.git` and `.gitattributes`). + +If you attempt to enter the details of a folder that is already configured as a Git repository, then GitHub desktop will prompt you to add this repository instead. + +You can now create your theme inside this local repository. + +To publish your local repository to GitHub: + +1. Go to GitHub Desktop and click the “**Publish repository”** button. +2. If you aren’t already, you will be asked to sign into your GitHub account. +3. Name your public repository; you can give it any name, but it’s a good idea to keep it the same name as the theme folder. You can also select whether you want your code to be public or private using the checkbox provided. +4. Click **“Publish Repository**“. + +Once published, you should be able to see your repository with your theme code on GitHub. + +## If you’re working on a new plugin + +First, you’ll need to create a local repository inside of your plugin folder: + +1. In GitHub Desktop, click the “**Create a New Repository on your Local Drive…**” button or navigate to *File > New Repository*. +2. In the “**Repository Name**” field, type the name of the plugin you’re developing. It should match the name of the plugin in your `wp-content/plugins/` folder. +3. In the “**Local Path**” field, select the `wp-content/plugins/` folder in your Studio site (the path will look something like this: `/Users/user_name/Studio/site_name/wp-content/plugins`). +4. Click “**Create Repository**“. + +Once you click the “**Create Repository**” button, you will have created a local repository. Two hidden files will be added to your individual theme folder (`.git` and `.gitattributes`). + +If you attempt to enter the details of a folder that is already configured as a Git repository, then GitHub desktop will prompt you to add this repository instead. + +To publish your local repository to GitHub: + +1. Go to GitHub Desktop and click the “**Publish Repository**” button. +2. Name your public repository; you can give it any name, but it’s a good idea to keep it the same name as the theme folder. You can also select whether you want your code to be public or private using the checkbox provided. +3. Click “**Publish Repository**“. + +Once published, you should be able to see your repository with your plugin code on GitHub. + +## If you want to sync all `wp-content` files + +If you’re not working on a specific plugin or theme and want to place a full site under version control, we recommend only tracking what’s inside the `wp-content` folder. This is where all your customizations are stored that make your site unique. The majority of WordPress core files usually remain unchanged and can be re-downloaded if necessary. The `wp-config.php` file is an exception, as it contains essential configuration details, primarily for your database connection. + +If you want to sync the full website, including the database, consider using [Studio Sync](https://developer.wordpress.com/docs/developer-tools/studio/sync/). While version control is not provided by Studio Sync itself, you can use this feature alongside GitHub-based development workflows. + +First, you’ll need to create a local repository in your site `wp-content` folder: + +1. In WordPress Studio, select your site and click on the **Overview** tab. +2. Under the “**Open in…**“ section, open the site folder in your [chosen code editor](https://developer.wordpress.com/docs/developer-tools/studio/sites/#6--open-in-section). +3. Create a file named `.gitignore` inside the `wp-content` folder. +4. Add the following folder and file names to this new `.gitignore` file to avoid tracking them in your repository. This will exclude the plugins required by Studio, your SQLite database, and your uploads folder. **For this reason your posts, pages and images from your local site won’t be committed to your production site.** + +``` +mu-plugins +database +db.php +uploads +``` + +mu-plugins database db.php uploadsCopyCopied + +1. In GitHub Desktop, click the “**Create a New Repository on your Local Drive…**” button or navigate to *File > New Repository*. +2. In the “**Repository Name**” field, type `wp-content`, to match the name of your `wp-content` folder. +3. In the “**Local Path**” field, select the folder of your Studio site (the path will look something like this: `/Users/user_name/Studio/site_name`). +4. Click “**Create Repository**“. + +Once you click the “**Create Repository**” button, you will have created a local repository. Two hidden files will be added to your individual theme folder (`.git` and `.gitattributes`). + +To publish your local repository to GitHub: + +1. Go to GitHub Desktop and click the “**Publish Repository**” button. +2. Name your public repository; you can give it any name. You can also select whether you want your code to be public or private using the checkbox provided. +3. Click “**Publish Repository**“. diff --git a/content/runtime/documentation/get-started/index.md b/content/runtime/documentation/get-started/index.md new file mode 100644 index 0000000..d11acc6 --- /dev/null +++ b/content/runtime/documentation/get-started/index.md @@ -0,0 +1,40 @@ +--- +type: document +title: Get started +description: "" +resource: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/get-started/" +tags: +timestamp: "2026-06-16T19:29:28+00:00" +wordpress: + id: 2510 + status: publish + type: documentation + author: 0 + date: "2026-06-16 19:29:28" + date_gmt: "2026-06-16 19:29:28" + modified: "2026-06-16 19:29:28" + modified_gmt: "2026-06-16 19:29:28" + slug: get-started + parent: 0 + menu_order: 0 + comment_status: closed + ping_status: closed + guid: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/get-started/" + comment_count: 0 +--- + +[Business and Commerce WordPress.com plans](https://wordpress.com/hosting/?ref=developer-docs#pricing-grid) come equipped with the features and tools that help developers and agencies create streamlined workflows. + +One of the most important features is [GitHub Deployments](https://wordpress.com/support/github-deployments/), which lets you deploy code changes directly from GitHub—a widely-used platform for code development—to your production or staging site. + +The following steps will guide you through creating a new WordPress.com site, setting up your local environment using [WordPress Studio](https://developer.wordpress.com/docs/developer-tools/studio), pushing your plugin, theme, or full site code to GitHub, and deploying your changes. + +- [Step 1: Create a site](https://developer.wordpress.com/docs/get-started/create-site/) +- [Step 2: Set up your local environment](https://developer.wordpress.com/docs/get-started/local-environment-setup/) +- [Step 3: Set up GitHub](https://developer.wordpress.com/docs/get-started/github/) +- [Step 4: Develop locally](https://developer.wordpress.com/docs/get-started/develop-locally/) +- [Step 5: Deploy to your production or staging site](https://developer.wordpress.com/docs/get-started/deploy/) + +Although this development workflow is ideal for most scenarios, especially if you want version control, an alternative option is [Studio Sync](https://developer.wordpress.com/docs/developer-tools/studio/sync/). This feature lets you synchronize your production or staging WordPress.com site with your local WordPress Studio site in either direction, eliminating the need for GitHub Deployments. + +Studio Sync is perfect when Git version control isn’t available or required, you need to push or pull an entire WordPress site, or you’re making content and Site Editor changes locally. diff --git a/content/runtime/documentation/get-started/local-environment-setup.md b/content/runtime/documentation/get-started/local-environment-setup.md new file mode 100644 index 0000000..40faf4c --- /dev/null +++ b/content/runtime/documentation/get-started/local-environment-setup.md @@ -0,0 +1,47 @@ +--- +type: document +title: "Step 2: Set up your local environment" +description: "" +resource: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/local-environment-setup/" +tags: +timestamp: "2026-06-16T19:29:24+00:00" +wordpress: + id: 2471 + status: publish + type: documentation + author: 0 + date: "2026-06-16 19:29:24" + date_gmt: "2026-06-16 19:29:24" + modified: "2026-06-16 19:29:30" + modified_gmt: "2026-06-16 19:29:30" + slug: local-environment-setup + parent: 2510 + menu_order: 0 + comment_status: closed + ping_status: closed + guid: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/local-environment-setup/" + comment_count: 0 +--- + +For local development, we recommend using [WordPress Studio](https://developer.wordpress.com/studio/?ref=developer-docs), a free, open source development environment for WordPress sites created by the WordPress.com team. It’s currently available for Mac and Windows. + +[Download Studio](https://developer.wordpress.com/studio/?ref=developer-docs) + +## Create a blank WordPress Studio site + +You may choose to start from scratch. If that’s the case, you can create a blank WordPress site through WordPress Studio by [following these instructions](https://developer.wordpress.com/docs/developer-tools/studio/sites/#0-add-a-new-site). + +## Import content into WordPress Studio + +If you have existing content to import into WordPress Studio, you have two options. To import an entire site, you can: + +- Use [Studio Sync](https://developer.wordpress.com/docs/developer-tools/studio/sync/) to pull content from an existing WordPress.com site into Studio automatically. [Follow these instructions](https://developer.wordpress.com/docs/developer-tools/studio/sync/#pull) to get started. +- Use the [importing feature](https://developer.wordpress.com/docs/developer-tools/studio/import-export/) within Studio if your site is hosted elsewhere. +- Use a preconfigured site [Blueprint](https://developer.wordpress.com/docs/developer-tools/studio/blueprints). + +To import custom plugin or theme code, you can upload ZIP files through wp-admin or add files directly into the correct folder through Finder or File Explorer: + +- If importing a plugin, add files to the `wp-content/plugins` folder. +- If importing a theme, add files to the `wp-content/themes` folder. + +By default, all Studio sites are located in the `Studio` folder in the root directory of your computer. diff --git a/content/runtime/documentation/glance/glossary.md b/content/runtime/documentation/glance/glossary.md new file mode 100644 index 0000000..36abe37 --- /dev/null +++ b/content/runtime/documentation/glance/glossary.md @@ -0,0 +1,78 @@ +--- +type: document +title: Glossary +description: "" +resource: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/glossary/" +tags: +timestamp: "2026-06-16T19:29:24+00:00" +wordpress: + id: 2478 + status: publish + type: documentation + author: 0 + date: "2026-06-16 19:29:24" + date_gmt: "2026-06-16 19:29:24" + modified: "2026-06-16 19:29:30" + modified_gmt: "2026-06-16 19:29:30" + slug: glossary + parent: 2476 + menu_order: 0 + comment_status: closed + ping_status: closed + guid: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/glossary/" + comment_count: 0 +--- + +This glossary defines key terms and concepts related to both the WordPress ecosystem and the WordPress.com hosting platform. + +| **Action** | One of two types of hooks; Actions allow you to change how WordPress works at specific points during the execution of WordPress Core, plugins, and themes. [Learn more about Actions](https://developer.wordpress.org/plugins/hooks/actions/). | +|---|---| +| **Activity Log** | The [Jetpack Activity Log](https://developer.wordpress.com/docs/troubleshooting/jetpack-activity-log/) shows a record of all activities and events on your WordPress.com website so you can keep track of your site’s changes. | +| **Backup** | Create copies of your WordPress website’s files and database to protect against data loss or corruption. The [Jetpack VaultPress Backup](https://developer.wordpress.com/docs/platform-features/real-time-backup-restore/) backs up your site automatically on eligible WordPress.com plans. | +| **Bandwidth** | The amount of data that can be transferred between a website and its visitors within a specific period, usually measured in megabytes per second (MBPS). All websites hosted on WordPress.com have unmetered bandwidth, so you don’t have to compromise on speed and performance when your website receives large amounts of traffic. | +| **Block Editor** | The default content editor introduced in WordPress 5.0, also known as Gutenberg. Use it to create content like pages and posts using a block-based approach, providing a more intuitive and flexible editing experience compared to the classic editor. | +| **Blocks** | Blocks are the fundamental units of content in the block editor. Blocks exist for text, media, code, payments, menus, embeds, and [much more](https://wordpress.com/support/wordpress-editor/blocks/). They are individual components that can be combined and arranged to create rich and dynamic page layouts. | +| **Cache** | A temporary storage mechanism used to store frequently-accessed data, such as web pages or database queries, to improve website performance and reduce server load. The [global network of data centers](https://wordpress.com/support/clear-your-sites-cache/) on WordPress.com serves content to your visitors more quickly, no matter where they are in the world. | +| **CDN** | A **C**ontent **D**elivery **N**etwork consists of distributed servers strategically located across different geographic regions to deliver website content, such as images, CSS files, and scripts, to visitors more efficiently. The built-in CDN on WordPress.com, known as the [Site Accelerator](https://wordpress.com/support/site-accelerator-cdn/), improves website performance and reliability by reducing latency and bandwidth usage. | +| **Child theme** | A WordPress theme that inherits the functionality and styling of a parent theme. Developers use [child themes](https://wordpress.com/support/themes/child-themes/) to make modifications and customizations to the theme without altering the original theme files, making updates and maintenance easier. | +| **CMS** | A **C**ontent **M**anagement **S**ystem is a software application used to create, manage, and publish digital content, such as websites, blogs, and online stores. WordPress is the most-used CMS in the world, powering over 43% of all websites. | +| **CPUs** | **C**entral **P**rocessing **U**nits determine the processing power available to handle website requests and server tasks. Websites hosted on WordPress.com use high-frequency CPUs to process queries at incredible speeds. | +| **Cron** | Cron jobs are used for time-based tasks, like publishing scheduled posts and performing background maintenance on WordPress sites. | +| **Custom fields** | Custom fields provide a way to store and display structured data beyond the default content fields. You can add additional metadata or custom information to posts, pages, or custom post types using manual development or a custom fields plugin. | +| **Custom post type** | Create diverse content structures with other content types (beyond standard posts and pages) that have custom fields, taxonomies, and templates. [Plugin-enabled WordPress.com plans](https://wordpress.com/hosting/?ref=developer-docs#pricing-grid) include the ability to add your own custom post types via plugins and custom development. | +| **Database** | The database stores website content, settings, and user information. WordPress.com website owners can use [phpMyAdmin](https://developer.wordpress.comhttps://wordpress.com/support/database/) to access the database and run a wide range of MySQL operations for efficient storage, retrieval, and manipulation. | +| **DDOS** | **D**istributed **D**enial of **S**ervice is a type of cyber attack in which multiple compromised computer systems, often infected with malware, are used to flood a target website or server with an overwhelming amount of traffic, causing it to become slow or unavailable to legitimate users. WordPress.com websites come protected against DDOS attacks as standard. | +| **DNS** | The **D**omain **N**ame **S**ystem translates human-readable domain names, such as yourgroovydomain.com, into numerical IP addresses that computers can understand. [Add DNS records to your domain](https://developer.wordpress.com/docs/platform-features/domain-management/) to give specific instructions for email, subdomains, verification with other services, and much more. | +| **Domain** | A unique and human-readable name that identifies a website on the internet, such as yourgroovydomain.com. You can [register a domain name](https://developer.wordpress.com/docs/platform-features/domain-management/#0-register-a-new-domain) on WordPress.com for free with any annual plan, or [transfer a domain name](https://wordpress.com/support/domains/incoming-domain-transfer/) from another provider. | +| **Elasticsearch** | A distributed search and analytics engine used for indexing and searching large volumes of structured and unstructured data in real time. Elasticsearch is used for [all posts on WordPress.com](https://developer.wordpress.com/docs/elasticsearch/) to implement advanced search functionality. | +| **Filter** | A function or hook in WordPress that modifies or manipulates data before it is displayed or processed. Filters are commonly used to customize the behavior of WordPress core features, themes, and plugins. | +| **Five for the Future** | An [initiative](https://wordpress.org/five-for-the-future/) supported by the WordPress community encouraging individuals and organizations to dedicate 5% of their time and resources to contributing back to the WordPress project, including code contributions, documentation, support, and community building. | +| **GitHub Deployments** | The process of deploying code changes or updates to a WordPress website using GitHub, a popular code hosting platform. Developers can use [GitHub Deployments on WordPress.com](https://wordpress.com/support/github-deployments/) to manage and track changes to their WordPress projects efficiently. | +| **Gutenberg** | The code name for the **block editor** introduced in WordPress 5.0, named after Johannes Gutenberg, the inventor of the printing press. [Gutenberg](https://wordpress.org/plugins/gutenberg/) revolutionized content creation in WordPress by introducing a block-based editing experience. | +| **Hook** | A point in the WordPress execution cycle where developers can insert custom code or modify behavior using action and filter hooks. Hooks allow developers to extend and customize WordPress functionality without directly modifying core files. | +| **Jetpack** | Our popular WordPress plugin that provides a suite of features and tools for website management, security, performance, backups, and content creation. [Jetpack](https://jetpack.com/) is included as standard with all WordPress.com sites. | +| **JSON** | **J**ava**S**cript **O**bject **N**otation is a lightweight data interchange format commonly used for transmitting data between a web server and a web application. JSON is human-readable and easy to parse, making it ideal for exchanging structured data. | +| **Malware** | **Mal**icious soft**ware** designed to disrupt, damage, or gain unauthorized access to a website through vulnerabilities in themes and plugins. Websites hosted on WordPress.com include [automated malware scanning](https://wordpress.com/support/malware-and-site-security/) & one‑click fixes to keep your site ahead of security threats. | +| **NGINX** | A high-performance, open-source web server software used to serve web content and handle HTTP requests. NGINX is used on WordPress.com for its efficiency, scalability, and ability to handle large volumes of concurrent connections. | +| **Patterns** | [Pre-designed combinations of blocks](https://developer.wordpress.com/docs/guides/block-patterns/) in the WordPress block editor that can be easily inserted into posts and pages to create complex layouts and designs. Patterns help users streamline the content creation process and maintain consistency across their website. | +| **PHP** | A popular server-side scripting language used for web development, particularly well-suited for creating dynamic web pages and interacting with databases. WordPress is primarily written in PHP. | +| **Plugin** | A piece of software that extends the functionality of a WordPress website by adding new features, modifying existing functionality, or integrating with third-party services. WordPress.com websites on paid plans can choose from over [50,000 plugins](https://wordpress.com/plugins) (or upload your own plugins) to add virtually any capability to a WordPress site. | +| **Query** | A request made to the WordPress database to retrieve specific information, such as posts, pages, or custom content types, based on specified criteria. Queries are used to generate dynamic content on WordPress websites. | +| **REST API** | A set of rules and conventions for building web services that allow for communication between different software applications across the internet. The [WordPress.org REST API](https://developer.wordpress.com/docs/api/) provides developers with a way to access and interact with WordPress data programmatically. The [WordPress.com REST API](https://developer.wordpress.com/docs/api/) offers similar functionality to the WordPress.org REST API but is tailored to the WordPress.com environment and ecosystem. | +| **SFTP** | **S**ecure **F**ile **T**ransfer **P**rotocol provides encrypted communication between a client and a server for transferring files. Use [SFTP on WordPress.com](https://wordpress.com/support/sftp/) to upload, download, and manage files on web servers securely. | +| **Shortcode** | A WordPress-specific code enclosed in square brackets used to embed dynamic content onto a page. For example, `[youtube]` embeds a YouTube video. Shortcodes have been used less frequently since the introduction of the block editor. | +| **Site Editor** | Supported on modern block themes, the [Site Editor](https://wordpress.com/support/site-editor/) provides the highest level of flexibility to design the entire website, including the header, footer, sidebars, and other site-wide elements, all in a graphical interface. | +| **Sitemap** | A structured list of URLs for all pages and content on a website, intended to help search engines crawl and index the site more effectively. WordPress.com includes [built-in sitemaps](https://wordpress.com/support/sitemaps/) located at `sitemap.xml`. | +| **SSH** | **S**ecure **SH**ell allows you to use a terminal application to access the backend of your site and manage certain site files and settings. [SSH is available](https://wordpress.com/support/ssh/) on eligible WordPress.com plans. | +| **SSL** | A security protocol that encrypts data transmitted between a web server and a web browser, ensuring that sensitive information, such as passwords, credit card numbers, and personal data, remains private and secure. [SSL certificates and HTTPS encryption](https://en.support.wordpress.com/domains/https-ssl/) are included as standard for all WordPress.com websites. | +| **Staging site** | A clone or replica of a live website created for testing purposes used to safely experiment with changes, updates, or new features without affecting the live (production) site. Use [staging sites on WordPress.com](https://wordpress.com/support/how-to-create-a-staging-site/) to help minimize the risk of errors and downtime during development and deployment. | +| **Taxonomy** | A system for organizing and classifying content into hierarchical or non-hierarchical groups based on shared characteristics or attributes. Categories and tags are the most commonly used taxonomies on WordPress to organize posts, pages, and custom content types. | +| **Template** | A file or set of files that define the structure and layout of specific types of pages or content within a WordPress theme. Templates control how different elements, such as headers, footers, sidebars, and content, are displayed on the front end of a website. | +| **Theme** | A collection of files, including templates, stylesheets, and JavaScript files that determine the visual design and layout of a WordPress website. Themes allow users to customize the appearance of the website without modifying the underlying code. | +| **Uptime** | The percentage of time that a website or server is operational and accessible to users over a given period, typically measured in hours or days. WordPress.com hosting has an unbeatable 99.999% uptime. | +| **VideoPress** | A video hosting and streaming service integrated with WordPress.com, allowing users to upload, manage, and embed videos on their WordPress websites. [VideoPress](https://wordpress.com/support/videopress/) provides tools for transcoding, streaming, and displaying high-quality videos without third-party plugins or services. | +| **Widget** | A small, self-contained block of content or functionality that can be added to widget-ready areas, such as sidebars, footers, and other widget-enabled sections of a WordPress theme. Widgets can display various types of content, including text, images, navigation menus, and custom functionality. Widgets have been used less frequently since the introduction of the block editor. | +| **WordPress** | An open-source content management system (CMS) written in PHP and MySQL, used to create and manage websites, blogs, and online stores. WordPress powers over 43% of websites worldwide and is known for its flexibility, extensibility, and user-friendly interface. | +| **WordPress.com** | A managed WordPress host, provided by Automattic. [WordPress.com hosting](https://wordpress.com/hosting/?ref=developer-docs#pricing-grid) provides a simplified website-building experience for users of all skill levels. | +| **WordPress Studio** | [A free, open source desktop app from WordPress.com](https://developer.wordpress.com/docs/developer-tools/studio) that allows you to easily build and maintain local WordPress websites without manual server setup or tool configuration. You can also share your local work publicly through temporary demo sites, sync local sites with those hosted on WordPress.com, and more. | +| **WP-CLI** | **W**ord**P**ress **C**ommand **L**ine **I**nterface is a tool for managing and administering WordPress installations from the command line or terminal. [WP-CLI on WordPress.com](https://developer.wordpress.com/docs/developer-tools/wp-cli/) provides commands for performing common tasks, such as installing plugins, updating themes, and managing users, without the need of a web browser. | diff --git a/content/runtime/documentation/glance/index.md b/content/runtime/documentation/glance/index.md new file mode 100644 index 0000000..3ad87e7 --- /dev/null +++ b/content/runtime/documentation/glance/index.md @@ -0,0 +1,48 @@ +--- +type: document +title: At a glance +description: "" +resource: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/glance/" +tags: +timestamp: "2026-06-16T19:29:24+00:00" +wordpress: + id: 2476 + status: publish + type: documentation + author: 0 + date: "2026-06-16 19:29:24" + date_gmt: "2026-06-16 19:29:24" + modified: "2026-06-16 19:29:24" + modified_gmt: "2026-06-16 19:29:24" + slug: glance + parent: 0 + menu_order: 0 + comment_status: closed + ping_status: closed + guid: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/glance/" + comment_count: 0 +--- + +Welcome, this is your go-to resource for learning how to effectively manage sites on WordPress.com using our suite of developer tools. Whether you’re just getting started or already building at scale, you’ll find comprehensive documentation, tutorials, and guides to support your workflow. + +If you’re not yet hosting your sites on WordPress.com, there are a few ways to get started. + +## Sign up to WordPress.com + +For individuals or small teams managing between **one and four sites**, we recommend signing up directly through WordPress.com. Our managed WordPress hosting includes unmetered bandwidth, fast performance, enterprise-grade security, and intuitive multi-site management—all starting at just $25/month. To take full advantage of our [developer tools](https://developer.wordpress.com/docs/developer-tools/), be sure to choose a **Business** or **Commerce** plan. + +[Get WordPress.com hosting](https://wordpress.com/hosting/?ref=developer-docs#pricing-grid) + +If you’re managing **five or more sites**, [Automattic for Agencies](https://wordpress.com/for-agencies/) is the best place to start. It offers access to WordPress.com hosting with agency-friendly pricing, referral earnings, premier support, and powerful tooling—all with a free initial setup. + +[Explore Automattic for Agencies](https://wordpress.com/for-agencies/) + +## Next steps + +After signing up, take some time to explore the platform and its features. Whether you need basic hosting tools or advanced development workflows, WordPress.com provides everything you need to build and manage world-class WordPress sites. + +- [WordPress and WordPress.com](https://developer.wordpress.com/docs/glance/wordpress-and-wordpress-com/) +- [Tech stack](https://developer.wordpress.com/docs/glance/tech-stack/) +- [Glossary](https://developer.wordpress.com/docs/glance/glossary/) +- [Interface styles](https://developer.wordpress.com/docs/glance/interface-styles/) +- [Support](https://developer.wordpress.com/docs/glance/support/) diff --git a/content/runtime/documentation/glance/interface-styles.md b/content/runtime/documentation/glance/interface-styles.md new file mode 100644 index 0000000..17f4180 --- /dev/null +++ b/content/runtime/documentation/glance/interface-styles.md @@ -0,0 +1,49 @@ +--- +type: document +title: Interface styles +description: "" +resource: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/interface-styles/" +tags: +timestamp: "2026-06-16T19:29:24+00:00" +wordpress: + id: 2473 + status: publish + type: documentation + author: 0 + date: "2026-06-16 19:29:24" + date_gmt: "2026-06-16 19:29:24" + modified: "2026-06-16 19:29:30" + modified_gmt: "2026-06-16 19:29:30" + slug: interface-styles + parent: 2476 + menu_order: 0 + comment_status: closed + ping_status: closed + guid: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/interface-styles/" + comment_count: 0 +--- + +WordPress.com offers two admin dashboard interface options for managing your site: **Default** and **Classic**. This guide explains the differences between the two styles and how to switch between them. + +## Style overview + +You can choose between two admin styles when managing your site: + +- **Default style:** A modernized, user-friendly version of the classic WordPress experience with sleek post/page management, easy profile edits, built-in tips and resources for your site, and more. +- **Classic style:** The traditional WordPress dashboard, featuring the classic black sidebar. This interface is commonly used in tutorials and guides across the web. If you are migrating from another hosting provider, this is likely the interface you are most familiar with. + +![A screenshot of the default view on the WordPress.com dashboard.](https://developer.wordpress.com/wp-content/uploads/2024/11/default-view-wordpress-com-interface-style.jpeg)Default style + +![A screenshot of the wp-admin view on the WordPress.com dashboard.](https://developer.wordpress.com/wp-content/uploads/2024/11/wp-admin-wordpress-com-interface-style.jpeg)Classic style (WP Admin view) + +Both views allow you to complete all major site management tasks. The choice comes down to personal preference. + +## Switching interface styles + +To set the admin interface style for your site: + +1. Visit your site’s dashboard. +2. Navigate to *Settings → General*. +3. Scroll down to the “**Admin Interface Style**” section. +4. Choose between “**Classic style**” or “**Default style**” options. +5. Click the “**Save Settings**” button. Your admin interface style will update automatically in a few seconds. diff --git a/content/runtime/documentation/glance/support.md b/content/runtime/documentation/glance/support.md new file mode 100644 index 0000000..38c099a --- /dev/null +++ b/content/runtime/documentation/glance/support.md @@ -0,0 +1,76 @@ +--- +type: document +title: Support +description: "" +resource: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/support/" +tags: +timestamp: "2026-06-16T19:29:27+00:00" +wordpress: + id: 2494 + status: publish + type: documentation + author: 0 + date: "2026-06-16 19:29:27" + date_gmt: "2026-06-16 19:29:27" + modified: "2026-06-16 19:29:30" + modified_gmt: "2026-06-16 19:29:30" + slug: support + parent: 2476 + menu_order: 0 + comment_status: closed + ping_status: closed + guid: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/support/" + comment_count: 0 +--- + +WordPress.com is a managed hosting platform that runs the open-source WordPress software. As part of our commitment to making development and site management easier, we offer several ways to get support based on your hosting plan and needs. + +This guide explains the support options available, what’s covered, and how to contact our team. + +## Support options + +- **Paid plans:** Customers on [WordPress.com paid plans](https://wordpress.com/plans/) have access to fast, expert support—available 24/7. +- **Free plans:** Users on the free plan can receive help from the community through the [WordPress.com public forums](https://wordpress.com/forums/). + +## Scope of support + +We are more than happy to answer questions related to WordPress.com and provide advice or suggestions for your site. Feel free to ask us anything related to your website’s development, design, customization, coding, and hosting. This can include: + +- Troubleshooting issues with WordPress.com-hosted sites. +- Help with built-in features like backups, staging, and the block editor. +- Questions about code (HTML, CSS, or JavaScript) when used within the platform. +- Questions about WordPress.com developer tools such as WP-CLI, SFTP/SSH, and GitHub Deployments. + +### What’s not covered + +While we’ll do our best to point you in the right direction, some things fall outside the scope of support, including but not limited to: + +- Support for [third-party plugins, themes, and tools](https://wordpress.com/support/plugins/get-help-with-plugins-and-themes/) not purchased or managed through WordPress.com. +- Making direct changes inside accounts with other providers (such as domain registrars). +- Assistance for self-hosted WordPress sites that are **not hosted on WordPress.com**. +- Writing or editing large portions of custom code (including HTML and CSS). +- Providing support for services managed by other teams or platforms. + +### Related support channels + +Depending on what you’re working with, there are several other support teams available for services like Jetpack, Akismet, Jetpack Mobile, and the REST API: + +- [Jetpack](https://jetpack.com/contact-support/): For questions about the Jetpack plugin on self-hosted WordPress sites. +- [Akismet](https://akismet.com/contact/): If comments are being incorrectly marked as spam. +- [WordPress.com REST API](https://developer.wordpress.com/docs/api/): For technical documentation and guidance on using the REST API. +- [Jetpack Mobile or WordPress.com Desktop Apps](https://apps.wordpress.com/support/): For issues related to our mobile and desktop apps. + +## How to get support + +To get help from the WordPress.com support team: + +1. Visit your website’s dashboard. +2. Click the question mark icon in the top right corner to open the **Help Center**: + +![The question mark WordPress.com help center icon on the Admin Bar, highlighted with an orange box around it.](https://developer.wordpress.com/wp-content/uploads/2024/02/help-center-icon-on-admin-bar.png)1. Use the box to search our help guides, covering all aspects of WordPress.com—it’s possible the answer to your question can be found here. +2. If you can’t find your issue in the list and still want to contact us, click “**Still need help?**” at the bottom of the Help Center: + +![An arrow pointing to the 'Still need help' button in the WordPress.com Help Center.](https://developer.wordpress.com/wp-content/uploads/2024/02/help-center.png)1. Type your question or issue into the Support Assistant and submit. After a few seconds, our system will provide an automated response to attempt to solve your trouble. +2. If the quick response answers your question, click the X icon to close the Support Assistant. If you are still stuck and would like like to submit your request to our support team, click the link to “**Contact our support team**“. + +When you contact the WordPress.com support team, a confirmation email will be sent to the email address associated with your account. If you don’t see it in your inbox, be sure to check your spam or junk folder in case it was filtered there. diff --git a/content/runtime/documentation/glance/tech-stack.md b/content/runtime/documentation/glance/tech-stack.md new file mode 100644 index 0000000..e92ddcf --- /dev/null +++ b/content/runtime/documentation/glance/tech-stack.md @@ -0,0 +1,91 @@ +--- +type: document +title: Tech stack +description: "" +resource: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/tech-stack/" +tags: +timestamp: "2026-06-16T19:29:24+00:00" +wordpress: + id: 2474 + status: publish + type: documentation + author: 0 + date: "2026-06-16 19:29:24" + date_gmt: "2026-06-16 19:29:24" + modified: "2026-06-16 19:29:30" + modified_gmt: "2026-06-16 19:29:30" + slug: tech-stack + parent: 2476 + menu_order: 0 + comment_status: closed + ping_status: closed + guid: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/tech-stack/" + comment_count: 0 +--- + +When you create a site on WordPress.com, you benefit from a robust, fully managed tech stack designed to enhance performance, security, and growth. This page outlines the key features that come standard with your WordPress.com site and explains their importance. + +Many of these features are available on sites with the [WordPress.com Business or Commerce plan](https://wordpress.com/hosting/?ref=developer-docs#pricing-grid). + +## Pre-installed plugins + +WordPress.com plans include a curated set of pre-installed plugins to provide speed, security, and flexibility from the start. [View the full list of pre-installed plugins](https://developer.wordpress.com/docs/guides/symlinked-files-folders/#symlinked-plugins). + +Here are a few notable examples: + +- **[Jetpack](https://wordpress.com/plugins/jetpack):** Offers built-in security, performance optimization, backups, and growth tools—all in one plugin. +- **[Akismet](https://wordpress.com/plugins/akismet):** Filters out spam comments and contact form submissions automatically. +- **[Classic Editor](https://wordpress.com/plugins/classic-editor):** Restores the original WordPress editor for those who prefer the classic experience (inactive by default). +- **[Crowdsignal Forms](https://wordpress.com/plugins/crowdsignal-forms):** Lets you create polls, surveys, and feedback forms directly in the block editor. +- **[Crowdsignal Polls & Ratings](https://wordpress.com/plugins/polldaddy):** Adds poll and rating management tools to your WordPress dashboard. +- **[Gutenberg](https://wordpress.com/plugins/gutenberg):** Provides access to experimental features and upcoming WordPress core updates. +- **[Layout Grid](https://wordpress.com/plugins/layout-grid):** Allows for flexible, grid-based page layouts with adjustable columns. +- **[Page Optimize](https://wordpress.com/plugins/page-optimize):** Optimizes JavaScript and CSS delivery for faster page loads. + +Jetpack and Akismet are the only two plugins that must stay installed and activated, as they optimize WordPress.com sites with important security and storage features. + +## Developer tools + +The WordPress.com Business and Commerce plans include advanced tools built for developers: + +- **Custom Code**: Add JavaScript and other code modifications for greater flexibility in site functionality, tracking, and third-party integrations. +- **SFTP and SSH Access**: [Manage and edit files](https://wordpress.com/support/sftp/) on your WordPress site via file transfer tools like FileZilla and [use the command line](https://wordpress.com/support/ssh/) to access your server for advanced configurations and management tasks. +- **MySQL Database Access**: [Access your site database](https://developer.wordpress.comhttps://wordpress.com/support/database/) via phpMyAdmin to manage your site’s backend data. +- **Server-Side Caching Management**: [Built-in caching](https://wordpress.com/support/clear-your-sites-cache/) and options to clear the cache as needed—no third-party plugins required. +- **Staging Sites**: Each site includes a [staging environment](https://wordpress.com/support/how-to-create-a-staging-site/) for safe testing before pushing changes live. +- **GitHub Deployments**: [Link your site with a GitHub repository](https://wordpress.com/support/github-deployments/) so any changes made in your repository can be automatically pushed to your live or staging environment. +- **REST API Integration**: [Send and receive data](https://developer.wordpress.com/docs/api/) from your WordPress site via HTTP requests for powerful integrations with third-party applications and services. + +## Hosting features + +Paid plans on WordPress.com include fully managed hosting and performance enhancements: + +- **Managed WordPress Hosting**: Powerful hosting is included alongside the WordPress software on WordPress.com, so you don’t need to sign up with another host. +- **Automatic Updates**: WordPress core, PHP, and optionally your themes and plugins are updated automatically. +- **Storage**: Each site includes between 6 GB and 50 GB of storage by default, depending on the [site’s plan](https://wordpress.com/plans/). You can purchase add-ons to increase your storage by up to 300 GB. +- **Themes and Patterns**: Choose from a wide selection of mobile-ready [themes](https://wordpress.com/themes/) and [block patterns](https://wordpress.com/patterns) to easily launch a professional website that reflects your brand identity. +- **Plugin Access**: Download your favorite plugins from [our plugin repository](https://wordpress.com/plugins) or upload your own. +- **Visitor Stats**: Access detailed analytics to track performance and engagement. Optional integration with Google Analytics is also supported. +- **24/7 Expert Support**: [Get help from our team](https://developer.wordpress.com/docs/glance/support/) of Happiness Engineers whenever you need it. + +## Marketing and growth features + +WordPress.com gives you built-in tools to grow and engage your audience: + +- **Unlimited Traffic:** No bandwidth caps or traffic limits—your site stays fast no matter how many visitors it gets. +- **Newsletters & RSS:** Keep your audience informed with [built-in email newsletters](https://wordpress.com/support/newsletter/send-newsletter-emails/) and [RSS feed](https://en.support.wordpress.com/feeds/) support. +- **Social Sharing:** Automatically [publish your posts](https://wordpress.com/support/post-automatically-to-social-media/) to major social media platforms. +- **Search Engine Optimization**: Essential SEO features are included on all plans. Business and Commerce plans unlock advanced SEO tools and premium plugins like [Yoast](https://wordpress.com/plugins/wordpress-seo). +- **Monetization Tools:** [Accept payments](https://en.support.wordpress.com/monetize-your-site/) through Stripe to sell products, offer subscriptions, restrict content, or collect donations. + +## Security features + +Security is built into the foundation of every WordPress.com site: + +- **Free SSL Certificates**: We include [free SSL](https://en.support.wordpress.com/domains/https-ssl/) with all domains used on a WordPress.com site, ensuring your site always loads over HTTPS. +- **Spam Prevention**: Automatically filter out spam comments with our Akismet tool. +- **Jetpack Scan**: [Jetpack Scan](https://developer.wordpress.com/docs/platform-features/jetpack-scan/) detects vulnerabilities and security threats in plugins, themes, and files. +- **Real-time Backups**: [Daily automated backups](https://developer.wordpress.com/docs/platform-features/real-time-backup-restore/) provide peace of mind, so you can easily recover previous versions of the site if needed. +- **Site Activity Log**: [Monitor recent changes](https://developer.wordpress.com/docs/troubleshooting/jetpack-activity-log/) made on your site and maintain oversight of your site’s activities by all users. + +When you choose WordPress.com, you’re equipped with a robust platform that comes pre-loaded with essential features to help you build, manage, and grow your website efficiently. Whether you’re building a blog, a business site, or a high-traffic online store, WordPress.com provides a modern, developer-friendly platform with powerful tools and features to help you succeed. diff --git a/content/runtime/documentation/glance/wordpress-and-wordpress-com.md b/content/runtime/documentation/glance/wordpress-and-wordpress-com.md new file mode 100644 index 0000000..8f20df2 --- /dev/null +++ b/content/runtime/documentation/glance/wordpress-and-wordpress-com.md @@ -0,0 +1,75 @@ +--- +type: document +title: WordPress and WordPress.com +description: "" +resource: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/wordpress-and-wordpress-com/" +tags: +timestamp: "2026-06-16T19:29:24+00:00" +wordpress: + id: 2475 + status: publish + type: documentation + author: 0 + date: "2026-06-16 19:29:24" + date_gmt: "2026-06-16 19:29:24" + modified: "2026-06-16 19:29:30" + modified_gmt: "2026-06-16 19:29:30" + slug: wordpress-and-wordpress-com + parent: 2476 + menu_order: 0 + comment_status: closed + ping_status: closed + guid: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/wordpress-and-wordpress-com/" + comment_count: 0 +--- + +[WordPress](https://wordpress.org) is an open-source content management system (CMS) that powers over 43% of websites on the internet. It’s a flexible, extensible platform built for publishing—from blogs and portfolios to enterprise-level applications. + +**WordPress.com**, on the other hand, is a managed hosting platform that runs the open-source WordPress software. It offers a streamlined, secure, and performance-optimized environment where you can build and manage WordPress websites without worrying about server setup, software updates, or maintenance. + +This page explains how WordPress and WordPress.com relate to one another and outlines what developers can expect when working on WordPress sites hosted on WordPress.com. + +## What is WordPress? + +WordPress is a free, open-source CMS developed by a global community of contributors. Originally launched in 2003 as a blogging platform, it has since evolved into a powerful system for building everything from personal websites to complex applications. + +Key benefits of WordPress include: + +- **Open Source:** Anyone can view, modify, and redistribute the WordPress code. +- **User-Friendly:** Built with an intuitive interface for users of all skill levels. +- **Customizable:** Thousands of themes and plugins let you tailor the look and functionality of your site. +- **SEO-Friendly:** Designed with SEO in mind, with support from numerous SEO plugins. +- **Developer Ecosystem:** A vast and active global community contributes to core development, plugin and theme creation, and community support. +- **Secure and Up-to-Date:** Regular security patches and updates help keep sites safe. +- **Mobile Ready:** Most themes are responsive by default for a better experience across devices. + +You can download the WordPress software for free at [WordPress.org](https://wordpress.org) and install it on the web host of your choice. + +## Hosting WordPress on WordPress.com + +[WordPress.com](https://wordpress.com/hosting/) is a managed hosting service created by Automattic, a company founded by one of the original WordPress co-creators. It runs the open-source WordPress software but removes the complexity of server configuration, performance tuning, manual updates, and more. + +With WordPress.com, you can: + +- Create and manage multiple sites from a single dashboard. +- Get built-in support for [real-time backups](https://developer.wordpress.com/docs/platform-features/real-time-backup-restore/), [staging sites](https://wordpress.com/support/how-to-create-a-staging-site/), and object caching. +- Access a suite of [essential developer tools](https://developer.wordpress.com/docs/developer-tools/), including [WP-CLI](https://developer.wordpress.com/docs/developer-tools/wp-cli/), [GitHub deployments](https://wordpress.com/support/github-deployments/), and [SFTP](https://wordpress.com/support/sftp/)/[SSH](https://wordpress.com/support/ssh/). +- Benefit from automatic WordPress updates and unmetered bandwidth. +- Rely on enterprise-grade security, 99.999% uptime, and [global edge caching](https://wordpress.com/support/clear-your-sites-cache/) for performance. +- Reach out to [24/7 expert support](https://developer.wordpress.com/docs/glance/support/) for help when needed. + +To take full advantage of the developer tools and performance features, we recommend choosing a **Business** or **Commerce** plan. + +## Working with databases on WordPress.com + +WordPress uses a MySQL database to store site content and configuration settings—everything from posts and pages to plugin settings and user data. Tables such as `wp_posts`, `wp_users`, and `wp_options` are foundational to any WordPress installation. MySQL is known for its speed and reliability, making it suitable for handling all types of WordPress sites. + +On WordPress.com, database access is provided through **phpMyAdmin**, a web-based tool for managing MySQL databases. This allows you to view and interact with your database using a graphical interface, without needing to use command-line tools. For full instructions, [visit our Database Access support page](https://developer.wordpress.comhttps://wordpress.com/support/database/). + +## PHP versioning on WordPress.com + +WordPress is primarily written in PHP. Like any programming language, PHP evolves over time, with new versions offering performance improvements, new features, and security fixes. + +While self-hosted WordPress sites require developers to manage their own PHP versions, WordPress.com takes care of this for you. Your sites will always run on a secure, actively supported PHP version without the need for manual upgrades. + +You can view the currently supported PHP versions on our [PHP environment support page](https://wordpress.com/support/php-environment/). diff --git a/content/runtime/documentation/guides/add-http-headers.md b/content/runtime/documentation/guides/add-http-headers.md new file mode 100644 index 0000000..4bd5cfa --- /dev/null +++ b/content/runtime/documentation/guides/add-http-headers.md @@ -0,0 +1,104 @@ +--- +type: document +title: Add HTTP headers +description: "" +resource: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/add-http-headers/" +tags: +timestamp: "2026-06-16T19:29:25+00:00" +wordpress: + id: 2482 + status: publish + type: documentation + author: 0 + date: "2026-06-16 19:29:25" + date_gmt: "2026-06-16 19:29:25" + modified: "2026-06-16 19:29:30" + modified_gmt: "2026-06-16 19:29:30" + slug: add-http-headers + parent: 2479 + menu_order: 0 + comment_status: closed + ping_status: closed + guid: "https://bountiful-impassioned-hygiea.wpcloudstation.dev/developer-wordpress-com-documentation/add-http-headers/" + comment_count: 0 +--- + +This guide will show you how to add HTTP Headers to your WordPress.com website to handle various requests and responses. + +This feature is available on sites with the [WordPress.com Business or Commerce plan](https://wordpress.com/hosting/?ref=developer-docs#pricing-grid). + +## About HTTP headers + +HTTP Headers pass additional information alongside an HTTP request or response on your website. HTTP headers will instruct your site on how to handle certain requests and gather information, depending on the source, service, or social network that the header code originates from. + +Most HTTP headers are optimized on WordPress.com and will not require changing, but many can also be applied or modified on your website if you require it. Bear in mind that some HTTP header codes are not modifiable on WordPress.com if they present a security threat or if they conflict with other functions on the WordPress.com platform. + +### List of common HTTP headers + +Below is a table displaying common HTTP headers that can be applied to your site, with applicable notes on which HTTP headers cannot be modified on WordPress.com. You may also learn more about different [HTTP Headers from MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers). + +| Header | Description | +|---|---| +| **X-Robots-Tag** | Indicates how a web page will be indexed within public search engine results. The HTTP header is effectively equivalent to ``. | +| [Access-Control-Allow-Headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Headers) | Used in response to a preflight request, which includes the Access-Control-Request-Headers to indicate which HTTP headers can be used during the actual request. | +| [Access-Control-Allow-Methods](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Methods) | Specifies one or more methods allowed when accessing a resource in response to a preflight request. | +| [Access-Control-Allow-Credentials](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Credentials) | Tells browsers whether to expose the response to the frontend JavaScript code when the request’s credentials mode (Request.credentials) is `include`. | +| [Access-Control-Allow-Origin](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Origin) | Indicates whether the response can be shared with requesting code from the given origin. | +| [Access-Control-Expose-Headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Expose-Headers) | Allows a server to indicate which response headers should be made available to scripts running in the browser in response to a cross-origin request. | +| [X-Frame-Options](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Frame-Options) | Indicates whether or not a browser should be allowed to render a page in a ``, `