.TH Foundry 1 "November 2025"
.\" Please adjust this date whenever revising the manpage.
.\"
.\" Some roff macros, for reference:
.\" .nh        disable hyphenation
.\" .hy        enable hyphenation
.\" .ad l      left justify
.\" .ad b      justify to both left and right margins
.\" .nf        disable filling
.\" .fi        enable filling
.\" .br        insert line break
.\" .sp <n>    insert n+1 empty lines
.\" for manpage-specific macros, see man(7)
.SH NAME
foundry \- a command line development environment

.SH SYNOPSIS
.B foundry
.RI [OPTION]...
.RI COMMAND
.RI [COMMAND\-OPTIONS]...
.br

.SH DESCRIPTION
.B foundry
is a development environment and build system designed for the GNOME desktop.
It provides project management, build pipeline integration, SDK management,
and various development tools for building applications and libraries.

.SH COMMANDS

.SS Project Commands

.TP
.BR init
Initialize a new project in the current directory.

.SS Environment Commands

.TP
.BR enter
Enter the environment of the project in the current directory.

.TP
.BR devenv\ [--\ command]
Enter the build environment for the project similar to the build pipeline.

.TP
.BR shell\ [--\ command]
Start a shell in the project environment or run command.

.SS File Commands

.TP
.BR guess\-language
Detect the programming language of a file.

.TP
.BR grep
Grep files using the search and replace mechanism of Foundry.

.TP
.BR symbol\-tree\ FILE
List symbols in
.B FILE
as a tree.

.TP
.BR find\-symbol\-at\ FILE\ LINE\ LINE_OFFSET
Find the symbol at a specific position in
.B FILE
at
.B LINE
and
.B LINE_OFFSET
(both starting from 1).
Use
.B --tree
to print parent symbols as a tree.

.TP
.BR ctags\ FILE
Index
.B FILE
using the ctags service and output the ctags data to stdout.

.SS Build Commands

.TP
.BR build
Build the current build pipeline.

.TP
.BR run\ [--\ command]
Run a project command in the runtime environment.

.SS Pipeline Commands

.TP
.BR pipeline\ info
Show information about the build pipeline.

.TP
.BR pipeline\ flags
Show build flags for the build pipeline.

.TP
.BR pipeline\ targets
List build targets for the build pipeline.

.TP
.BR pipeline\ which
Show which pipeline is active.

.TP
.BR pipeline\ invalidate
Invalidate the pipeline cache.

.TP
.BR pipeline\ link\ PHASE\ PROJECT_DIRECTORY\ LINKED_PHASE
Link a workspace to the build pipeline. The stage will run at
.B PHASE
of the current pipeline and execute the linked pipeline at
.B LINKED_PHASE.

.TP
.BR pipeline\ unlink\ PHASE\ PROJECT_DIRECTORY
Unlink a workspace from the build pipeline. Removes entries matching
.B PHASE
and
.B PROJECT_DIRECTORY
from the linked workspaces.

.SS Configuration Commands

.TP
.BR config\ list
List available configurations.

.TP
.BR config\ switch
Change the active configuration.

.SS SDK Commands

.TP
.BR sdk\ list
List available SDKs.

.TP
.BR sdk\ install\ SDK_ID
Install a specific SDK.

.TP
.BR sdk\ switch\ SDK_ID
Change the active SDK for the build pipeline.
This will update your current configuration to use the SDK when possible.

.TP
.BR sdk\ shell\ SDK_ID
Enter a shell in the SDK environment.

.TP
.BR sdk\ which\ PROGRAM
Show where

.SS Dependencies Commands

.TP
.BR dependencies\ list
List project dependencies.

.TP
.BR dependencies\ update
Update project dependencies.
This does not build the dependencies.
Use
.B foundry\ build
to build the dependencies.

.SS Device Commands

.TP
.BR device\ list
List available devices.

.TP
.BR device\ switch
Switch the current target device.

.SS Deployment Commands

.TP
.BR deploy
Deploy the project to the active device.

.SS Test Commands

.TP
.BR test\ list
List available unit tests.

.TP
.BR test\ run\ TEST_ID
Run a unit test.

.SS Search Commands

.TP
.BR search
Use global search engine to search across project.

.TP
.BR show\ FILE
Open
.B FILE
in the preferred file browser.

.SS Settings Commands

.TP
.BR settings\ get\ SCHEMA\ KEY
Get a setting value applying the priority of settings from the user
overrides, project settings, and application-wide settings in that
order.

.TP
.BR settings\ set\ SCHEMA\ KEY\ VALUE
Set a setting value. Use
.B --global
to make the setting the user default.
Use
.B --project
to make the setting the project default including other users who
clone the project.
Otherwise, the setting applies to the current user for the current
project only.

.SS Secret Commands

.TP
.BR secret\ get\-api\-key HOSTNAME SERVICE
Get an API key from the secret store.
For example,
.B foundry\ secret\ get\-api\-key gitlab.gnome.org gitlab

.TP
.BR secret\ check\-expires\-at HOSTNAME SERVICE
Check when an API key expires for a service on a specific hostname.
The expiration date will be printed in local timezone.

.TP
.BR secret\ rotate HOSTNAME SERVICE
Rotate an API key for a service on a specific hostname.
The API key will be rotated using a registered key rotator plugin
and the new key will be stored securely.

.TP
.BR secret\ set\-api\-key HOSTNAME SERVICE API_KEY
Store an API key in the secret store.

.SS Diagnosis Commands

.TP
.BR diagnose\ FILE
Diagnose issues with
.B FILE

.SH CONDITIONAL COMMANDS

The following commands are only available when certain features are enabled
at build time:

.SS Git Commands (requires feature-git)

.TP
.BR clone
Clone a repository into a new project directory.

.SS Documentation Commands (requires feature-docs)

.TP
.BR doc\ bundle\ install
Install a specific documentation bundle.

.TP
.BR doc\ bundle\ list
List available documentation bundles.

.TP
.BR doc\ query\ KEYWORD
Search for documentation.

.SS Forge Commands (requires feature-forge)

.TP
.BR forge\ list
List available forge integrations.

.TP
.BR forge\ issues\ list
List issues from the forge.

.TP
.BR forge\ merge\-requests\ list
List merge requests from the forge.

.TP
.BR forge\ project
Show information about the forge project.

.TP
.BR forge\ switch\ FORGE_ID
.TP
.BR forge\ switch\ \-\-clear
Switch the active forge integration.
Use
.B --clear
to clear the forge setting instead of setting it.

.TP
.BR forge\ user
Show information about the forge user.

.SS Text Editing Commands (requires feature-text)

.TP
.BR grep
Search for text patterns in source files.

.SS LLM Commands (requires feature-llm)

.TP
.BR llm\ list\-models
List available language models.

.TP
.BR llm\ list\-resources
List available resources.

.TP
.BR llm\ list\-tools
List available LLM tools.

.TP
.BR llm\ complete
Complete text using a language model.

.SS MCP Commands (requires feature-mcp)

.TP
.BR mcp
Run MCP server.
The server communicates via stdin/stdout using the Model Context Protocol.

.SS LSP Commands (requires feature-lsp)

.TP
.BR lsp\ list
List available language server plugins.

.TP
.BR lsp\ prefer
Set preferred LSP for a language.

.TP
.BR lsp\ run
Run a language server for a specific language.

.SS Template Commands (requires feature-templates)

.TP
.BR template\ create
Create a new project from a template.

.TP
.BR template\ list
List available project templates.

.SS Version Control Commands (requires feature-vcs)

.TP
.BR vcs\ blame
Show blame information for files.

.TP
.BR vcs\ fetch
Fetch changes from remote repositories.

.TP
.BR vcs\ ignored
List ignored files.

.TP
.BR vcs\ list
List version control information.

.TP
.BR vcs\ list\-branches
List branches in the repository.

.TP
.BR vcs\ list\-files
List files tracked by version control.

.TP
.BR vcs\ list\-remotes
List remote repositories.

.TP
.BR vcs\ list\-tags
List tags in the repository.

.TP
.BR vcs\ log\ FILE
Show commit history for FILE.

.TP
.BR vcs\ switch
Switch branches or checkouts.

.SH OPTIONS

.TP
.BR \-\-shared
Use shared mode for the command.

.TP
.BR \-h ", " \-\-help
Show help information for the command.

.SH EXAMPLES

Initialize a new project:
.RS
.B foundry init
.RE

Build the project:
.RS
.B foundry build
.RE

Run a project command:
.RS
.B foundry run
.RE

Enter the build environment:
.RS
.B foundry devenv
.RE

List available SDKs:
.RS
.B foundry sdk list
.RE

Install an SDK:
.RS
.B foundry sdk install org.gnome.Sdk/x86_64/master
.RE

Start a language server:
.RS
.B foundry lsp run python3
.RE

.SH FEATURES
Foundry may be compiled with various features disabled or removed.
Some commands may be unavailable if the underlying feature was not
compiled into your version of Foundry.

.SH SEE ALSO
For further information, visit the website
https://devsuite.app/

.SH BUGS
Bug reports can be found and filed at
https://gitlab.gnome.org/chergert/foundry/issues