CLI and APIs
Use the commands that gh does not have
Some features of the forge have no gh command, and you want them in your terminal too. src has commands for your profile, MCP servers, apps, monorepos, architecture and impact, the software factory, and to wait for changes.
8 min read
Without -R, a command acts on the repository of your clone.
Wait for changes
src watch follows the live event stream of the forge, and prints each change as one JSON line. It replaces a poll loop in a script or an agent.
| You want to | Command |
|---|---|
| Wait until the checks of a pull request are done | src watch checks 7 --exit-status |
| Wait until a CI run completes | src watch run <run> --exit-status |
| Follow the log of a CI job until it completes | src watch job <job> --run <run> --log |
| Wait for a push to a branch | src watch --events push --branch main |
| Follow a pull request: its changes, checks and pushes | src watch pr 7 |
See Wait for CI, merges and pushes with src for the events, the flags and the exit codes.
Your profile
Use your own token: an agent token cannot change a profile.
| You want to | Command |
|---|---|
| Change your profile fields, like your timezone | src profile edit --timezone Europe/Berlin |
| Change your image | src profile set-image avatar.png |
| Read the README of your profile | src profile readme view |
| Write the README of your profile | src profile readme set --file README.md |
Add --org <org> to act on an organization. Your profile and image has the details.
MCP servers
src mcp connects remote MCP servers to the factory agents of a repository, and writes them into the config of your local agents. With --org <name>, the connection commands act on an organization.
| You want to | Command |
|---|---|
| List the servers of the repository | src mcp list |
| Connect a server with a header token | src mcp connect linear --url <url> --header Authorization < key.txt |
| Pick the agents and the tools of a server | src mcp tools linear --agent triage --enable list_issues |
| List the tools of a server again | src mcp tools linear --refresh |
| Delete a server and its credential | src mcp disconnect linear |
Write the servers into .mcp.json and the other agent files | src mcp pull |
| Find, view or publish a server in the marketplace | src mcp server search, src mcp server view, src mcp server create |
connectreads the header values from standard input, one line for each--header, in order. A value never goes into your shell history.- In the example,
key.txtholds the full value, for exampleBearer lin_api_.... - A server that signs in with OAuth needs a browser. For such a listing,
connectprints the web page that connects it. - See Use the servers in your local agent for
src mcp pull.
Apps
src app manages the apps installed on a repository.
| You want to | Command |
|---|---|
| List the app installs that cover the repository | src app list |
| Take the repository out of an install that picked it | src app remove-repo <install-id> --yes |
| Uninstall an app from its account | src app uninstall <install-id> --yes |
src app listshows each install id. Add--json installId,app,repos,actions,eventsfor a script.remove-reponeeds admin rights on the repository.uninstallneeds you to own the account.- You register and install apps on the web. See Install an app.
Monorepos
src monorepo works with a monorepo: a repository whose members are other repositories of the same owner.
| You want to | Command |
|---|---|
| Clone the monorepo and every member | src monorepo clone acme/platform |
| Fetch every member, and clone new members | src monorepo sync |
| See the branch of each folder, ahead and behind | src monorepo status |
| List, add or remove members | src monorepo member list, src monorepo member add acme/docs, src monorepo member remove acme/docs |
| Search issues and pull requests in all members | src monorepo search issues "login fails" |
| Search code in all members | src monorepo search code "createRouter" |
| Open, view, list, merge, retry or close a monorepo pull request | src monorepo pr create --title "Add the field", src monorepo pr merge 12 |
- Run
sync,statusandpr createat the root of the checkout. member addtakes--folderfor a folder other than the name of the repository.- Without
-R, themembercommands act on the repository of your clone.
See Clone and sync a monorepo and Change several members in one pull request.
Architecture and impact
| You want to | Command |
|---|---|
| See the architecture of the repository | src repo architecture |
| Make the architecture now (write access) | src repo architecture --generate |
| See the impact of a pull request | src pr impact 12 |
| Find the pull requests to handle first | src pr list --ease easy --sort impact |
| Read or change the stack of a pull request | src pr stack view 12, src pr stack unlink 12, src pr stack link 12, src pr stack break 12 |
src pr impactalso takes a URL or a branch. Without one, it uses the pull request of the current branch.- Add
--json <fields>to get the fields of the REST answer, for a script or an agent.
Traffic and npm downloads
| You want to | Command |
|---|---|
| See who clones and visits the repository (write access) | src repo insights --range 30d |
| See the npm downloads of the packages of the repository | src repo npm |
| See the npm downloads of the public repositories of an organization | src org npm <org> |
src repo npmprints one line for each package: the name,verified, the latest version, the weekly downloads and the change.src org npm <org>prints the same lines, with the repository of each package.- Add
--json packagesto get the downloads of each day of the last 540 full days, up to yesterday.
The factory and bans
src factory runs the software factory, src deps runs its dependency agent, and src ban manages bans. With --org <name>, the settings, keys and ban commands act on an organization.
Settings and keys
| You want to | Command |
|---|---|
| See the factory settings | src factory settings |
| See what the forge-paid models cost this month, and the cap | src factory settings --org <org> --json spend |
| Turn on agents, or change the factory settings | src factory configure --file change.json |
| Save a model key | src factory set-key anthropic < key.txt |
set-keyreads the key from standard input, so the key does not go into your shell history.src factory keyslists the providers that have a key. It never shows a key.
A change file holds only the fields that you change. This file turns on the review and its fixes:
{ "agents": { "review": { "enabled": true, "steps": { "fix": true } } } }
agentstakes the agent ids:audit,spam,review,keep-green,summary,triage,assign,issue-fix,deps,architectureandci-cache.- These agents are on by default: the security audit (
audit),summary(its stepsimpactandclassify),architectureandci-cache. Every other agent is off by default. - The switches of an agent are in
steps. See Models, keys and triggers.
Runs and custom agents
| You want to | Command |
|---|---|
| See the runs on an issue or a pull request | src factory runs 12 |
| See the newest runs of the repository (write access) | src factory runs -L 20 |
| See only the failed runs of one agent, all its steps (write access) | src factory runs --agent review --status failed |
| Read one run and its log | src factory run <run id> --log |
| Add a custom agent | src factory upload-agent docs-check docs-check.ts |
| List the custom agent files, and the errors of the files | src factory agents |
src factory runsshows each run as its agent and its step, for examplereview/fixer. For the main step of an agent, it shows the agent alone, for exampleaudit.--json agent,stepgives the agent id and the step id.--agenttakes an agent id (all its steps) or a step id.src factory agentsprints the errors of the custom agent files on stderr, and exits 0. See Fix an error in the file.
Dependencies
| You want to | Command |
|---|---|
| See the dependencies and the pull requests of the dependency agent | src deps list |
| Check the dependencies now (write access) | src deps check |
| Set or remove the rule of a dependency (write access) | src deps rule set react --no-major, src deps rule remove react |
src deps rule set takes one of --ignore, --no-major or --ignore-version <version>. A scoped name such as @types/node works as it is.
Bans
| You want to | Command |
|---|---|
| Ban an account, or lift its ban | src ban add <user>, src ban remove <user> |
| See the spam signals of an account | src ban signals <user> |
| See the bans that the spam agent suggests | src ban suggestions |
| Ban the account of a suggested ban, or dismiss it | src ban accept <id>, src ban dismiss <id> |
src ban suggestions lists the open suggested bans. Add --state banned or --state dismissed for the decided ones.