I have read several blog posts and discussions about the url option in WP-CLI and have seen many different opinions and interpretations, so I assume I'm not alone with this question...

The official documentation says:

Pretend request came from given URL. In multisite, this argument is how the target site is specified.

Default value: null

What exactly does this mean, and why would you need to "pretend" something? Examples much appreciated.

My understanding of WP-CLI is that the site @aliases are the best way to target a site when you have multiple sites... so is this url option mostly relevant to Multisite Networks, since you can't target using @aliases?

And if so, why define a global default value for it in wp-cli.yml?

  • 1
    Hey! I noticed you've never accepted an answer as the correct answer on any of your questions, did my answer not satisfy your question? If so can you comment on it so I can improve it? If it did, please consider marking it as the accepted answer by clicking the tick button under the voting controls
    – Tom J Nowell
    Aug 8, 2022 at 23:17
  • @Tom Thanks I left a comment and after you responded, marked your answer as the solution... it sounds like WP.org could probably improve the explanation of url better to say something like "Primarily used in Multisite networks to specify a site when @aliases or other specification methods are unavailable" or etc. Aug 11, 2022 at 9:45

1 Answer 1


Lets say I have a single multisite install on my server, and in that multisite/network admin I have 3 blogs:

  • example.com ( root/primary/first site )
  • example.com/second
  • othersite.net

If I want to list posts on the main site example.com I can do this:

wp post list

But what if I want to list posts on the example.com/second blog? Or othersite.net blog? How would it know that's the site I wanted, not the root site? How does it know to load example.com/second or othersite.net's theme/plugins/etc?

Normally WordPress knows this because it's in the HTTP headers, but there are non in WP CLI. Instead I can do this by passing --url.

wp post list --url="https://othersite.net"

Now WP CLI executes the command, and WP is loaded, but it loads the plugins and theme of othersite.net, with the posts etc of othersite.net.

My understanding of WP-CLI is that the site @aliases are the best way to target a site when you have multiple sites...

When you have multiple installs or servers. If I have 2 multisites then 2 alias' are best, but that an alias doesn't help me differentiate between blogs/sites in an install of WordPress.

For example, I can't run a command on server A that executes on server B using --url that command would still be handled by that WP install even if that WP install isn't set up to handle that URL.

For example, on my server hosting my multisite website:

❯ wp option get siteurl
❯ wp option get siteurl --url="http://frontenberg.tomjn.com"
❯ wp option get siteurl --url="http://madeupsite.com"
Error: Site 'madeupsite.com' not found. Verify `--url=<url>` matches an existing site.

I can however use an alias to run WP CLI on my local machine, and have it automatically connect to a server and use a WordPress installation in a known location, as well as specifying certain things in advance to save time. E.g. I might use wp locally, but also have wp @dev and wp @staging and wp @production.

I might also use alias' for the same site/server but specify different options such as the current user etc. Note that alias' aren't used by everybody.

  • Thanks a lot Tom, one question: would it be accurate to say that the global url parameter (meaning the option hardcoded in the wp-cli.yml config file) is probably most useful in Multisite networks, and probably doesn't have as much relevance on single site servers, or servers with multiple sites that are targetable using @aliases? Aug 10, 2022 at 17:57
  • 1
    it's primary use is in multisites to specify which site URL to process the request as, I'm not sure why else you would use it, and I think you've blurred the lines between these and alias' too much. An alias is just a shortcut to save you typing lots of parameters on the end of every WP CLI command to make life easier
    – Tom J Nowell
    Aug 11, 2022 at 9:11
  • "it's primary use is in multisites to specify which site URL to process the request as, I'm not sure why else you would use it"... thanks, this is exactly what I've been trying to figure out, because I can't see any other use for url global parameter. Aug 11, 2022 at 9:37

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.