Skip to content

CLI Commands ​

Føhn provides #[AsCliCommand] for creating WP-CLI commands and includes built-in scaffolding commands. The built-in commands run as wp foehn <name>, the commands of your project as wp app <name>, and the commands of another package under the name of that package, such as wp foehn-acf <name> (see Command Namespace).

Built-in Commands ​

Føhn includes scaffolding and discovery management commands:

Scaffolding Commands ​

bash
# Generate a Timber model (with optional post type)
wp foehn make:model Product
wp foehn make:model Product --post-type

# Generate a post type, with meta fields and a URL slug
wp foehn make:post-type product
wp foehn make:post-type event --rewrite-slug=events --meta=start_date,venue,capacity:integer

# Generate a taxonomy
wp foehn make:taxonomy ProductCategory --post-types=product

# Generate a native block
wp foehn make:block Counter --interactive

# Generate a template controller
wp foehn make:controller single-product

# Generate a hooks class
wp foehn make:hooks Seo

# Generate a context provider
wp foehn make:context-provider Header

# Generate a context provider
wp foehn make:context GlobalContext --global
wp foehn make:context ProductContext --templates=single-product,archive-product

# Generate a block pattern
wp foehn make:pattern HeroWithCta

# Generate a shortcode
wp foehn make:shortcode Button

# Generate a navigation menu
wp foehn make:menu HeaderMenu --location=header
wp foehn make:menu FooterMenu --description="Footer Navigation"

# Generate an image size
wp foehn make:image-size CardImage --width=400 --height=300 --crop
wp foehn make:image-size HeroImage --width=1920 --height=0

# Generate a seeder
wp foehn make:seeder events --description="Sample events" --order=20

With studiometa/foehn-acf, the ACF commands go under wp foehn-acf:

bash
# Generate an ACF block
wp foehn-acf make:acf-block Hero

# Generate an ACF field group
wp foehn-acf make:field-group ProductFields --post-type=product
wp foehn-acf make:field-group PageFields --page-template=front-page
wp foehn-acf make:field-group CategoryFields --taxonomy=category

# Generate an ACF options page
wp foehn-acf make:options-page ThemeSettings
wp foehn-acf make:options-page FooterSettings --parent=theme-settings

Global Options ​

All scaffolding commands, the foehn-acf ones included, support these options:

bash
--force          # Overwrite an existing file, and run in production
--dry-run        # Write nothing: show the file that would be written
--format=json    # Print the result as JSON (default: text)

Example with dry-run:

bash
wp foehn make:post-type product --dry-run

Production Environment ​

A command that changes content or files does not run when wp_get_environment_type() is production. It writes nothing, says why and how to continue, and exits with status 1:

Error: `wp foehn seed` changes content or files, and wp_get_environment_type() is 'production', so it did not run. Run it on a local or staging copy, add --dry-run to see what it would do, or add --force to run it here.

These commands are guarded: seed, every make: command (the foehn-acf ones included), salts:generate and agents-md. Each one also takes --dry-run, which writes nothing and runs in production without --force.

--force lets the command run. On a make: command it also overwrites a file that exists, and on salts:generate it also replaces keys that are set. So run it with --dry-run first, to see what it would write.

The other commands are not guarded. db:export, inspect, errors, log, trace, verify, skill and the discovery:list, discovery:status and cache:status commands only read. cache:clear, cache:config --write, cache:warm, discovery:clear, discovery:generate and rewrite:flush are deploy steps: they rebuild what WordPress or Føhn derives from the code, and a deploy script runs them in production.

Check the environment before you run a command on a server: wp eval 'echo wp_get_environment_type();'.

Where a Generated Class Goes ​

A scaffolding command puts its class next to the classes of the same kind the project already declares. It reads them from discovery: a post type goes where the project's #[AsPostType] classes are, a block where its #[AsBlock] classes are, and so on.

  • The directory is the one that holds most of them. When each one has a directory of its own (Blocks/Hero/HeroBlock.php, Blocks/Quote/QuoteBlock.php), it is the directory that holds them all (Blocks/).
  • The namespace is theirs.
  • The parent class is the one most of them extend, when the stub extends a class. A post type of a project whose post types extend App\Models\BaseContent extends it too.

Only the classes under the app directory count, not the classes of the framework or of a package. When the project declares nothing of the kind, the command uses its default directory (Models/ for a post type, Blocks/ for a block…) and the stub's parent class. Run wp foehn discovery:clear first if the discovery cache is older than the classes you just added.

Post Types ​

make:post-type writes a model that registers the post type and its meta fields:

bash
wp foehn make:post-type event --rewrite-slug=events --meta=start_date,venue,capacity:integer
OptionEffect
--class=<class>The class name. Default: the PascalCase name (event gives Event).
--singular, --pluralThe labels. Default: the humanized name, and the singular with s.
--rewrite-slug=<slug>The URL slug of the single pages and the archive, as rewriteSlug of #[AsPostType]. Default: the name.
--meta=<fields>Meta fields, comma-separated, each key or key:type. The type is string (default), integer, number or boolean. Each field gets a #[AsPostMeta] and an accessor that reads it: start_date gives startDate(): ?string. The post type then supports custom-fields, so the block editor reads and saves the fields.

The class extends Studiometa\Foehn\Models\Post, which adds the query methods to Timber\Post, unless the project's post types share another parent (see above).

  • Store a date as a string in Y-m-d, or Y-m-d H:i:s, so a meta_query can compare it with the type DATE or DATETIME.
  • An array or object field needs a REST schema. Declare it with #[AsPostMeta] by hand.
  • No accessor is written when its name is a method of the parent class: a field date would replace Timber\Post::date(), which Timber and the templates call. The field is declared, and a note says to read it with post.meta('date') or to give the accessor another name.

The notes name the Twig files to create. For each of single-<name> and archive-<name>, they give the template controller that claims it, and a file next to the views of the same kind in the theme: the views of the other post types (pages/single-project.twig), or else the generic one (pages/single.twig). The controller picks the view at runtime, so read its render() or renderFirst() call to confirm. The notes also say where editors edit the meta fields (the Custom Fields panel, or blocks bound with core/post-meta), and that the rewrite rules need wp foehn rewrite:flush.

Scripts and Coding Agents ​

A scaffolding command never asks a question. Every value has a default or comes from an option, so a script or a coding agent can run it without a terminal:

  • A missing name is an error. The command writes nothing and exits with status 1.
  • A file that already exists is an error, unless you give --force. The command leaves the file as it is and exits with status 1. A --dry-run reports the same error, because the real run would refuse.
  • An unknown --format is an error, before anything is generated.

With --format=json, the command prints one JSON object on standard output. Errors go to standard error.

bash
wp foehn make:block hero --format=json
json
{
  "dryRun": false,
  "files": [{ "path": "/var/www/html/theme/app/Blocks/HeroBlock.php", "status": "created" }],
  "notes": ["Create the Twig template: templates/blocks/hero.twig"]
}
KeyValue
dryRuntrue when --dry-run was given.
files[].pathThe absolute path of the file.
files[].statuscreated, overwritten or exists (left as it is). With --dry-run: would-create, would-overwrite or exists.
files[].contentsWith --dry-run only: the contents the command would write.
notesThe next steps, for example the Twig file to create. Can be empty.

When the status is exists, the JSON is printed and the command then fails with status 1.

Project Inspection ​

bash
# What the project declares, by name: a summary to read whole
wp foehn inspect

# Some sections in full, as JSON for a program or a coding agent
wp foehn inspect post-types templates menus --format=json

# Every section in full
wp foehn inspect --all --format=json

inspect reports the project model from what discovery found. It reads the attributes the code declares, so it registers nothing and writes nothing. Run it before you write code in a project you do not know.

With no section, inspect prints a summary: each section with the names of its rows (post type names, WordPress templates, Twig views, menu locations, command names…). It is short enough to read whole. It starts with problems; wp foehn inspect problems gives the reason and the fix of each one (see Problems and Errors). Name one or more sections to print them in full, or pass --all for every section. --all cannot be combined with section names.

SectionWhat it lists
problemsWhat will not register: the classes discovery skipped and the type links that point at nothing, with the fix
post-typesPost types: the Timber model class, the arguments of #[AsPostType], the taxonomies and the #[AsPostMeta] fields
taxonomiesTaxonomies: the Timber model class, the arguments of #[AsTaxonomy], the post types and the term meta fields
settings#[AsSettingsPage] pages and the options they store: option name, type, default and sanitizer
blocks#[AsBlock] blocks: name, title, class, category, and each attribute with its type, default and allowed values
patterns#[AsBlockPattern] patterns: name, title, class and Twig template
bindings#[AsBlockBinding] sources: name, label, class and the block context they use
templatesEach WordPress template a controller claims: the controller that renders it, a URL to test it with, and its context keys
viewsEach Twig file of the theme: the context providers its view name matches, and its context keys
context-providersContext providers, the view names they match, and the keys each one adds
menusMenu locations and the Twig variable of each one (menus.<location>)
image-sizesImage sizes, with the name WordPress registers them under
rewrite-rules#[AsRewriteRule] rules: regex, query, query vars and class
rest-routes#[AsRestRoute] routes: path, HTTP method, permission and handler method
cli-commandsEvery WP-CLI command that discovery registered, with the full line that runs it: wp app <name>, wp foehn <name>, wp foehn-acf <name>
seeders#[AsSeeder] seeders, in the order wp foehn seed runs them: class, order and description
pluginsActive, network-activated and must-use plugins, with their versions
theme-supportsEvery add_theme_support() feature, with its arguments
viteThe entry points of the theme build (dist/.vite/manifest.json), and the dev server URL while npm run dev runs

A post type or taxonomy that Føhn does not register, such as post, category or a plugin's post type, is listed when a #[AsTimberModel] maps it to a class or a #[AsPostMeta] names it as its subtype. Its declared field is then false, model is null when no Timber model maps it, and the arguments only the registering code knows are null. A #[AsPostMeta] field with no subtype applies to every post type or taxonomy, so it is listed on each of them.

Where content is stored ​

Three sections say where content goes, so you can write it with core WP-CLI commands instead of guessing keys:

  • post-types and taxonomies: each #[AsPostMeta] field gives its key, type, default and single (false means one row per value). Write it with wp post meta update <id> <key> <value> or wp term meta update.
  • settings: each setting gives its option name, type, default and sanitize callback. Write it with wp option update <option> <value>. Every setting has a sanitizer: the one the page declares (sanitizeDeclared: true) or the one its type implies, such as sanitize_text_field for a string. Føhn calls register_setting() on init, and WP-CLI fires init before it runs a command, so wp option update saves through the same sanitizer as the admin form (sanitizeOnWpCli: true). A command run with --skip-themes does not load Føhn, and then no sanitizer runs.
  • blocks: each attribute gives its name, type, default and enum, which is what a block comment such as <!-- wp:theme/hero {"align":"center"} /--> in post_content may hold. The editor-only keys (control, label, …) are left out.

Template context ​

Two kinds of names meet in a template, and inspect reports them apart:

  • templates has one row per WordPress template a #[AsTemplateController] claims, such as single-product or archive-*. controller is the class that renders it. When several controllers claim the same template, the lowest priority wins (on a tie, the one discovered last), and overridden lists the others.
  • views has one row per Twig file in the theme's template directories (TimberConfig::templatesDir), named as render() names it: templates/pages/single.twig is pages/single. A child theme's file replaces the parent's file with the same name.

Context providers match view names, not WordPress templates. Which view a controller renders is decided at runtime (the starter's SingleController renders the first of pages/single-{post-type}-{slug}, pages/single-{post-type} and pages/single that exists), so inspect does not link a template to a view.

Both sections give the Twig variables that can be known without rendering. What all rows share is given once, next to the rows, so the sections stay short:

json
{
  "templates": {
    "base": [
      "body_class",
      "http_host",
      "menus",
      "post",
      "posts",
      "site",
      "theme",
      "user",
      "wp_title"
    ],
    "controllers": {
      "App\\Controllers\\TermController": { "priority": 10, "keys": ["children"], "partial": false }
    },
    "templates": [
      {
        "template": "taxonomy-*",
        "controller": "App\\Controllers\\TermController",
        "overridden": [],
        "request": ["term"]
      }
    ]
  },
  "views": {
    "base": [
      "body_class",
      "http_host",
      "menus",
      "post",
      "posts",
      "site",
      "theme",
      "user",
      "wp_title"
    ],
    "providers": {
      "App\\ContextProviders\\CardContextProvider": {
        "priority": 10,
        "keys": ["price_label"],
        "partial": false
      },
      "App\\ContextProviders\\GlobalContextProvider": {
        "priority": 10,
        "keys": ["current_year"],
        "partial": false
      }
    },
    "everyView": ["App\\ContextProviders\\GlobalContextProvider"],
    "views": [
      {
        "view": "components/card",
        "file": "templates/components/card.twig",
        "providers": ["App\\ContextProviders\\CardContextProvider"]
      },
      { "view": "pages/single", "file": "templates/pages/single.twig", "providers": [] }
    ]
  }
}
FieldWhat it holds
baseKeys that are always set: post, posts, site, user, the Timber global context (theme, http_host, wp_title, body_class), and menus when the project declares a #[AsMenu]. A value can be null (post on an archive, user for a visitor)
templates[].requestKeys that Timber::context() adds for the request that template answers, on top of base: term on a category, tag or taxonomy archive, search_query on search, author on author. A wildcard that reaches several kinds of request adds none
controllers, providersEach controller that claims a template, and each provider that matches a view, by class: its priority, its keys and partial. keys are read from the source of the class: each literal ->with('key', …) call in the class, its parent classes and their traits. A call can sit in a condition, so a key is not guaranteed at runtime. partial is true when the class also sets keys that only exist at runtime: with($name, …), merge() or withDto(). Its keys list is then incomplete
everyViewThe providers on *, which match every view name, in the order they run. They are not repeated on the rows
views[].providersThe other providers whose pattern matches that view, in the order they run. With everyView, they run in priority order

The tables give the same data: base and the providers in everyView with their keys are printed once above the rows, and each row shows the keys of its controller or of its own providers.

Test URLs ​

Each row of templates gives url, a real URL of the site that renders that template, so you can check a controller after you change it. When no URL renders it, url is null and noUrl gives the reason. The table prints the reason in the url column.

inspect reads one sample request of each kind from WordPress, and names it as Føhn names the request (single-{type}-{slug}, then single-{type}, then single):

SampleTemplate names
The home URLfront-page
The posts page, when Settings > Reading sets onehome
A search for testsearch
/foehn-not-found/404
The newest published post of each public post typesingle-…, or page-… for a page that is not the front page or the posts page
The archive of each public post type that has onearchive-{type}
The author and the month of the newest postauthor, date
The term with the most posts of each public taxonomycategory-…, tag-…, taxonomy-…

A template gets the first sample that it renders, not only one that its name matches: when single-* and single are both claimed, single-* takes every post (it claims single-post-hello-world, which comes before single), so single gets no URL and noUrl says Its sample URLs render 'single-*' instead. A name that Føhn gives to no request, such as tax-* (taxonomy archives are named taxonomy-…), gets Føhn gives no request a template name like this.

inspect reads one post of each type and one term of each taxonomy. A template that names a slug, such as page-contact, gets a URL only when that post is the newest one of its type; otherwise noUrl says The newest published post of each type does not render it.

wp foehn trace <url> then shows what the request ran. Reading the samples makes a few database queries and writes nothing.

Keys added elsewhere are not listed: a timber/context filter from a plugin, ViewEngine::share(), a helper class that a controller calls, and the keys a block's compose() returns. The controller's keys reach only the views it renders, and a Twig file included with {% include %} gets the context of the file that includes it.

With the FULL discovery cache, a class added after the cache was written is missing from the report until you run wp foehn discovery:clear.

JSON is printed on one line, without indentation. The full report has the section names as keys, also for one section, so a program reads report["post-types"] in all cases. Most sections are a list of rows; templates, views and vite are records that hold their rows (templates, views, entries) next to what the rows share. The summary has two keys: summary, an object with each section name as key and the list of its row names as value, and commands, the commands that print sections in full. An unknown section stops with an error that lists the valid names.

Agent Skills ​

bash
# The skills of the installed packages
wp foehn skill
wp foehn skill --format=json

# The main instructions of one skill
wp foehn skill foehn

# The reference files of a skill, then one of them
wp foehn skill foehn --list-references
wp foehn skill foehn --reference=blocks

skill prints the Agent Skills that the installed packages ship, at the versions in your project. It reads files only.

The skills come from two places:

  • every Composer package in vendor/composer/installed.json that has a skills/<name>/SKILL.md file. No package list is built in, so a third-party package that ships a skill is listed too;
  • node_modules/@studiometa/foehn-vite-plugin/skills, when the Vite plugin is installed.
OptionEffect
<name>Print the SKILL.md of this skill. Without it, the command lists the skills.
--reference=<file>Print a file of the skill's references/ directory instead. blocks, blocks.md and references/blocks.md give the same file.
--list-referencesList the reference files of the skill.
--format=jsonPrint a list as JSON.

The table gives the skill name, the package, its installed version and the first sentence of the description (from the SKILL.md frontmatter). The JSON gives the full description and also the path of the file relative to the project root, such as vendor/studiometa/foehn/skills/foehn/SKILL.md. An agent can read that path directly when WordPress cannot boot.

When two packages ship a skill with the same name, both are listed and wp foehn skill <name> prints the first: Composer packages come before the Vite plugin, in package name order. An unknown skill or reference stops with an error that lists the valid names.

AGENTS.md Block ​

bash
# Write or refresh the Føhn block in AGENTS.md
wp foehn agents-md

# Print the block and say what the command would do
wp foehn agents-md --dry-run

agents-md writes the Føhn block in the AGENTS.md file at the project root. The block holds a short list of what an agent does first in a Føhn project (inspect, the make: commands with --dry-run, seeders, errors, log and trace), then an index of the installed skills: one line for each skill and each reference file, with the command that prints it and the first sentence of the file. A skill line also gives the path of its SKILL.md, which an agent reads when WordPress cannot boot.

The block is between two markers:

html
<!-- foehn:begin -->
…
<!-- foehn:end -->
AGENTS.mdWhat the command does
MissingCreates it with the block only.
No markersAdds the block at the end of the file, after a blank line.
One begin marker, then one endReplaces what is between the markers. The text before and after them does not change.
Block already currentWrites nothing.
Other markers (one only, reversed, twice)Stops with an error and writes nothing. Fix the markers, or remove them, and run it again.

The index is built from the same sources as wp foehn skill, so it follows composer update and npm update when you run the command again. Commit the change. The block has no version numbers, so it changes only when a skill, a reference or the list of installed packages changes. A Markdown formatter such as Prettier or oxfmt leaves the block as it is.

OptionEffect
--dry-runWrite nothing. Print the block and say what the command would do.
--forceRun in the production environment. See Production Environment.

Composer does not run the command after composer install or composer update. It needs WordPress, which Composer does not boot, and a deploy that runs composer install would change a committed file on the server.

Seeders ​

bash
# Run every seeder, by order
wp foehn seed

# Run one seeder, by short or full class name
wp foehn seed --class=EventsSeeder

# List the seeders, in order, and run nothing
wp foehn seed --dry-run

seed runs the classes with #[AsSeeder], which write the sample content of the site. It stops with exit status 1 at the first seeder that throws an exception. A project with no seeder prints how to create one and exits with status 0. In production, it runs only with --force or --dry-run (see Production Environment). See Seeders.

Discovery Commands ​

bash
# List what discovery found, and where it came from
wp foehn discovery:list

# Scan every location and write the cache
wp foehn discovery:generate

# Clear the discovery cache
wp foehn discovery:clear

# Check cache status, per location, and list the classes discovery skipped
wp foehn discovery:status

The cache also fills itself on the first request that finds it missing, and composer install clears it. See Discovery Cache for more details on caching, and Listing what was found for discovery:list.

Rewrite Rules ​

bash
# Rebuild the rewrite rules, and forget the hash Foehn compares them against
wp foehn rewrite:flush

Foehn flushes on its own when the set of #[AsRewriteRule] declarations changes. This command is for when something else left the rules stale. See Rewrite Rules.

Verification ​

bash
# Fail a CI job when a WordPress or plugin update raised a diagnostic
wp foehn verify --profile=updates --output=build/foehn-verification.json

# Refuse to finish a deploy on unsafe production configuration
wp foehn verify --profile=production

Runs one named release gate and writes a deterministic JSON report. It exits 0 on a pass, 1 on actionable diagnostics or a failed check, and 2 when the gate could not run at all — so a CI job can tell a regression from a broken step. The profile is required and there is no flag to select individual checks. See Verification for both profiles, the report schema, and what each gate cannot observe.

Page Cache ​

bash
# Print the nginx rules that serve the cached pages, then write them
wp foehn cache:config --server=nginx
wp foehn cache:config --server=nginx --write

# Merge the Apache rules into web/.htaccess
wp foehn cache:config --server=apache --write

# Clear the whole cache, or one URL and its page/** subtree
wp foehn cache:clear
wp foehn cache:clear --url=https://example.com/blog/

# Say if the cache is on, where it stores pages, and what it holds
wp foehn cache:status

# Fill the cache from the sitemap: queue the URLs, or request them now
wp foehn cache:warm
wp foehn cache:warm --sync --limit=50

cache:config needs --server=nginx or --server=apache. With --write, it writes config/nginx/foehn-page-cache.conf, or merges a block into web/.htaccess. Run it again after you change app/page-cache*.config.php. cache:warm queues the URLs through Action Scheduler; without Action Scheduler, use --sync.

A deploy runs wp foehn cache:config --server=nginx --write && wp foehn cache:clear after composer install. With storage: PageCacheStorage::Bucket, every deploy must run wp foehn cache:clear. See Static Page Cache and Storing pages in the bucket.

Database Export ​

bash
# Write a light, anonymized dump of the database
wp foehn db:export

# Stream it from production to a local file
ssh production 'wp foehn db:export -' > db.sql.gz

# Keep one year of revisions and orders
wp foehn db:export db.sql.gz --from=-1year

Writes a gzipped SQL dump to import locally. Users, user meta, comments and WooCommerce orders are anonymized, transients are left out, and revisions and orders older than the window are left out. A table no rule covers is exported without rows and listed at the end. See Database Export for every rule, the config file, and what is not anonymized.

Errors ​

bash
# The last error, with the request that raised it
wp foehn errors

# The exceptions and fatal errors of the last hour, for an agent
wp foehn errors --level=exception,fatal --since=-1hour --limit=10 --format=json

# Start again from an empty log
wp foehn errors --clear

# The JavaScript errors of the pages the Vite dev server served
wp foehn errors --browser --level=error,rejection --limit=5

Prints the last errors the site recorded in the local and development environments: uncaught exceptions, fatal errors, and the warnings and notices of the theme's own code. Each entry gives the file and line, the Twig template and line, a short stack, the URL, the WordPress template, the controller, the view and its context keys. See The error log. With --browser, it prints the console errors and the uncaught errors of the pages that npm run dev serves, which @studiometa/foehn-vite-plugin writes with Vite 8. See Browser errors.

Debug Log ​

bash
# The last 20 groups of the WordPress debug log
wp foehn log

# The fatal errors and warnings of the last hour, for an agent
wp foehn log --level=fatal,warning --since=-1hour --format=json

# Every entry about one class
wp foehn log --grep=ProductController --limit=5

Reads wp-content/debug.log, or the file WP_DEBUG_LOG names, as entries with their level, message, file and line, and the stack trace of a fatal error. Entries that repeat are one group, with a count and the time of the first and the last. See The debug log.

Request Trace ​

bash
# Request a page and print what ran
wp foehn trace /about/

# The last request a browser made, or one by the id of its X-Foehn-Trace header
wp foehn trace last
wp foehn trace 3fa2c1 --format=json

# The last requests, one per line
wp foehn trace list --limit=20

Prints what a front-end request ran, in the local and development environments: its status, time and query count, the template files WordPress tried and the one it found, the controller, each Twig view with its context providers and keys, the blocks, and the errors of the request. See Request Trace.

Security Keys ​

WordPress signs authentication cookies and nonces with eight keys. They live in the environment, so a project keeps them wherever it keeps its other secrets. composer install fills them into .env on a first install, and the generated wp-config.php refuses to serve a production request without them.

bash
# Generate keys for a project that has none
wp foehn salts:generate

# Rotate them — this logs every user out
wp foehn salts:generate --force

# Say where the keys would go, and which keys would be replaced
wp foehn salts:generate --dry-run

Rotating replaces the keys the current cookies were signed with, so every session ends. In production, the command runs only with --force or --dry-run. A dry run never prints a key. Before it replaces keys that are set, the command asks for confirmation. --yes skips the question, for a script.

Where the keys come from ​

wp-config.php reads them in this order:

SourceNotes
config/wordpress-salts.config.phpOnly if a project chooses to use a PHP file. Read first, so it wins.
EnvironmentThe default. .env, container variables, a VM's environment, a secret pulled from a vault — anything that reaches PHP.

.env is untracked and managed per install; .env.example lists the eight names empty, so they are visible without being committed. A value that is empty or still starts with change-me- counts as absent.

Because the environment is read, nothing has to end up in a file at all: export the keys from your orchestrator or your vault and the installer leaves them alone. It checks for them before generating.

If you would rather keep them in a PHP file, write one and it takes precedence:

bash
wp foehn salts:generate --path=config/wordpress-salts.config.php

The command warns when that file exists and you rotate .env, since the file is what WordPress would still read.

Custom Commands ​

Create custom WP-CLI commands with #[AsCliCommand]. The commands of your project go under wp app, the commands of Føhn stay under wp foehn, and the commands of each other package go under a namespace of their own:

bash
wp app import:products products.csv   # A command of your project
wp foehn inspect                      # A command of Føhn
wp foehn-acf make:acf-block hero      # A command of studiometa/foehn-acf

A command of your project then cannot collide with a command that a later release of Føhn or of a package adds, and wp app lists only the commands of your site. wp foehn inspect cli-commands gives the line that runs each command.

Command Namespace ​

The namespace is the first word after wp. Each source of commands has its own:

SourceNamespaceExample
Your projectcliNamespace of FoehnConfig. Default: appwp app import:products
Føhn (studiometa/foehn)foehnwp foehn inspect
Another packageextra.foehn.cli-namespace of its composer.json. Default: the package name without its vendorwp foehn-acf make:acf-block

A class belongs to a package when it is in a PSR-4 directory of a package in vendor/composer/installed.json. This includes a package that Composer installs from a path repository with a symlink. The classes of the app directory of your theme belong to your project, also when your composer.json requires the theme as a package. Every other class belongs to your project.

The namespace of your project ​

To use another name than app, set cliNamespace in app/foehn.config.php:

php
<?php
// app/foehn.config.php

use Studiometa\Foehn\Config\FoehnConfig;

return new FoehnConfig(
    cliNamespace: 'site',
);

The name is one word of lowercase letters, digits, - and _. It cannot be foehn, because that namespace is for the commands of Føhn. The command of the example below is then wp site import:products. Change the cron jobs, deploy scripts and runbooks that call a command when you change the name.

The namespace of a package ​

The commands of a package go under its package name without the vendor: acme/shop-tools gives wp shop-tools <name>. To use another name, declare it in the composer.json of the package:

json
{
  "name": "acme/shop-tools",
  "extra": {
    "foehn": {
      "cli-namespace": "shop"
    }
  }
}

The commands of the package are then wp shop <name>. The rule is the same as for cliNamespace: one word of lowercase letters, digits, - and _, and not foehn. When the namespace of a package does not follow it, Føhn does not register the commands of the package and reports a problem in wp foehn inspect problems. This applies also to a package name that does not give a valid word, such as acme/foehn: declare a namespace for it.

Two classes for one command ​

When two classes declare the same command, for example a package and your project that both use the namespace shop and the name sync, Føhn registers neither of them. Each wp run prints a warning that names the two classes. Give one of them another name, or change the namespace of your project.

A Command Class ​

php
<?php
// app/Console/ImportProductsCommand.php

namespace App\Console;

use Studiometa\Foehn\Attributes\AsCliCommand;
use Studiometa\Foehn\Console\CliCommandInterface;
use WP_CLI;

#[AsCliCommand(
    name: 'import:products',
    description: 'Import products from CSV file',
    longDescription: <<<'DOC'
        ## OPTIONS

        <file>
        : Path to the CSV file

        [--dry-run]
        : Preview without importing

        ## EXAMPLES

            wp app import:products products.csv
            wp app import:products products.csv --dry-run
        DOC,
)]
final class ImportProductsCommand implements CliCommandInterface
{
    /**
     * @param array<int, string> $args Positional arguments
     * @param array<string, string> $assocArgs Named arguments
     */
    public function __invoke(array $args, array $assocArgs): void
    {
        $file = $args[0];
        $dryRun = isset($assocArgs['dry-run']);

        if (!file_exists($file)) {
            WP_CLI::error("File not found: {$file}");
        }

        $handle = fopen($file, 'r');
        $headers = fgetcsv($handle);
        $count = 0;

        while (($row = fgetcsv($handle)) !== false) {
            $data = array_combine($headers, $row);

            if ($dryRun) {
                WP_CLI::log("Would import: {$data['name']}");
            } else {
                $this->importProduct($data);
                WP_CLI::log("Imported: {$data['name']}");
            }

            $count++;
        }

        fclose($handle);

        WP_CLI::success("Processed {$count} products");
    }

    private function importProduct(array $data): int
    {
        $id = wp_insert_post([
            'post_type' => 'product',
            'post_title' => $data['name'],
            'post_content' => $data['description'] ?? '',
            'post_status' => 'publish',
        ]);

        if (isset($data['price'])) {
            update_post_meta($id, 'price', $data['price']);
        }

        return $id;
    }
}

Usage:

bash
wp app import:products /path/to/products.csv
wp app import:products /path/to/products.csv --dry-run

Command that Writes ​

Give writes: true to a command that changes content or files. In production, it then runs only with --force or --dry-run, like the commands of Føhn (see Production Environment). The command itself does not check the environment.

WP-CLI refuses an option the long description does not declare, so declare [--force] in longDescription. The refusal names --dry-run only when the long description declares [--dry-run].

php
#[AsCliCommand(
    name: 'import:products',
    description: 'Import products from a CSV file',
    longDescription: <<<'DOC'
        ## OPTIONS

        <file>
        : Path to the CSV file

        [--dry-run]
        : Import nothing. List the products that would be imported

        [--force]
        : Run in the production environment
        DOC,
    writes: true,
)]
final class ImportProductsCommand implements CliCommandInterface
{
    // ...
}

Command with Progress Bar ​

php
<?php

namespace App\Console;

use Studiometa\Foehn\Attributes\AsCliCommand;
use Studiometa\Foehn\Console\CliCommandInterface;
use WP_CLI;

#[AsCliCommand(
    name: 'images:optimize',
    description: 'Optimize all media library images',
)]
final class OptimizeImagesCommand implements CliCommandInterface
{
    public function __invoke(array $args, array $assocArgs): void
    {
        $attachments = get_posts([
            'post_type' => 'attachment',
            'post_mime_type' => 'image',
            'posts_per_page' => -1,
            'fields' => 'ids',
        ]);

        $total = count($attachments);

        if ($total === 0) {
            WP_CLI::warning('No images found');
            return;
        }

        $progress = \WP_CLI\Utils\make_progress_bar('Optimizing images', $total);

        foreach ($attachments as $id) {
            $this->optimizeImage($id);
            $progress->tick();
        }

        $progress->finish();
        WP_CLI::success("Optimized {$total} images");
    }

    private function optimizeImage(int $id): void
    {
        // Optimization logic
        wp_update_attachment_metadata($id, wp_generate_attachment_metadata(
            $id,
            get_attached_file($id)
        ));
    }
}

Command with Subcommands ​

A command class has one entry point, __invoke(). Føhn does not register other public methods as subcommands. For a command with more than one action, read the action from the first positional argument, and declare it in longDescription:

php
<?php

namespace App\Console;

use Studiometa\Foehn\Attributes\AsCliCommand;
use Studiometa\Foehn\Console\CliCommandInterface;
use WP_CLI;

#[AsCliCommand(
    name: 'object-cache',
    description: 'Manage the object cache',
    longDescription: <<<'DOC'
        ## OPTIONS

        <action>
        : What to do.
        ---
        options:
          - clear
          - stats
        ---

        ## EXAMPLES

            wp app object-cache clear
            wp app object-cache stats
        DOC,
)]
final class ObjectCacheCommand implements CliCommandInterface
{
    public function __invoke(array $args, array $assocArgs): void
    {
        match ($args[0]) {
            'clear' => $this->clear(),
            'stats' => $this->stats(),
        };
    }

    private function clear(): void
    {
        wp_cache_flush();
        WP_CLI::success('Cache cleared');
    }

    private function stats(): void
    {
        global $wp_object_cache;

        WP_CLI::log('Hits: ' . ($wp_object_cache->cache_hits ?? 'N/A'));
        WP_CLI::log('Misses: ' . ($wp_object_cache->cache_misses ?? 'N/A'));
    }
}

WP-CLI refuses an action that is not in the options list, so match gets only clear or stats. To give each action its own options, write one class for each action instead, for example object-cache:clear and object-cache:stats.

Usage:

bash
wp app object-cache clear
wp app object-cache stats

Command with Tables ​

php
#[AsCliCommand(
    name: 'products:list',
    description: 'List all products',
)]
final class ListProductsCommand implements CliCommandInterface
{
    public function __invoke(array $args, array $assocArgs): void
    {
        $products = get_posts([
            'post_type' => 'product',
            'posts_per_page' => -1,
        ]);

        if (empty($products)) {
            WP_CLI::warning('No products found');
            return;
        }

        $items = array_map(fn($p) => [
            'ID' => $p->ID,
            'Title' => $p->post_title,
            'Status' => $p->post_status,
            'Price' => get_post_meta($p->ID, 'price', true) ?: 'N/A',
        ], $products);

        WP_CLI\Utils\format_items(
            $assocArgs['format'] ?? 'table',
            $items,
            ['ID', 'Title', 'Status', 'Price']
        );
    }
}

Dependency Injection ​

Commands support constructor injection:

php
<?php

namespace App\Console;

use App\Services\ExportService;
use Studiometa\Foehn\Attributes\AsCliCommand;
use Studiometa\Foehn\Console\CliCommandInterface;
use WP_CLI;

#[AsCliCommand(
    name: 'export:orders',
    description: 'Export orders to CSV',
)]
final class ExportOrdersCommand implements CliCommandInterface
{
    public function __construct(
        private readonly ExportService $export,
    ) {}

    public function __invoke(array $args, array $assocArgs): void
    {
        $file = $this->export->ordersToCSV();
        WP_CLI::success("Exported to: {$file}");
    }
}

Long Description ​

Provide detailed help with longDescription:

php
#[AsCliCommand(
    name: 'sync:inventory',
    description: 'Sync inventory from external API',
    longDescription: <<<'DOC'
## DESCRIPTION

Synchronizes product inventory levels from the external inventory
management system.

## OPTIONS

[--force]
: Force sync even if recently updated

[--products=<ids>]
: Comma-separated product IDs to sync

## EXAMPLES

    # Sync all products
    wp app sync:inventory

    # Force sync specific products
    wp app sync:inventory --products=123,456 --force

## NOTES

This command requires API credentials in wp-config.php:
- INVENTORY_API_KEY
- INVENTORY_API_SECRET
DOC,
)]
final class SyncInventoryCommand implements CliCommandInterface
{
    public function __invoke(array $args, array $assocArgs): void
    {
        // ...
    }
}

Attribute Parameters ​

ParameterTypeDefaultDescription
namestringrequiredCommand name
descriptionstringrequiredShort description
longDescription?stringnullDetailed help (docblock)
writesboolfalseThe command changes content or files: in production, it runs only with --force or --dry-run

See Also ​

Føhn is released under the GPL-3.0-or-later license. The starter, the installer and the Vite plugin are MIT.