Install and set up the CLI#

You work in a terminal, and you want the forge there too: issues, pull requests, reviews and merges, with the gh commands that you know.

src is the CLI of TanStack Source. It takes the commands and flags of gh, and adds commands for the features that only TanStack Source has.

1. Install src#

src needs Node.js 22 or later.

On macOS, Linux, or Git Bash on Windows:

curl -fsSL https://gitflare.t-zlak97.workers.dev/install | sh

In Windows PowerShell:

irm https://gitflare.t-zlak97.workers.dev/install.ps1 | iex

Then open a new terminal.

• The script installs src in ~/.source/bin, or in %LOCALAPPDATA%\TanStackSource\bin on Windows.
• If that folder is not on your PATH, the script adds it or tells you how.
• To upgrade src, run the same command again.

2. Log in#

src auth login

1. src prints a one-time code. Press Enter to open the browser.
2. Type the code, click Continue, then click Approve.

An agent without a terminal of its own uses src auth login --web. It prints the code and the URL.

3. Let git use the same login#

src auth setup-git
src auth status

Now git clone, git pull and git push to the forge use your login. src auth status shows who you are.

4. Use your gh habits#

src takes gh's commands, so you can type gh. Add an alias.

In bash or zsh:

alias gh=src

In PowerShell:

Set-Alias gh src

To keep the alias, add the same line to ~/.bashrc, ~/.zshrc or your PowerShell $PROFILE. While the alias is on, gh runs src also in GitHub repositories. To run the real gh, type command gh in bash or zsh, or gh.exe in PowerShell.

To copy your gh aliases into src, see your gh aliases and settings.

Done#

In a clone of a repository on the forge, run:

src pr list
src issue list

You see the pull requests and the issues of the repository. src help support lists each command and flag that works now.

Next: keep your private files out of git, and get them back in each new clone.

Later: issues and pull requests#

These gh commands work in src too. Without -R, a command acts on the repository of your clone.

You want to	Command
See what needs you	src status, src issue status, src pr status
Lock, pin or delete an issue	src issue lock 12 --reason spam, src issue pin 12, src issue delete 12 --yes
Move an issue, or make a branch for it	src issue transfer 12 acme/docs, src issue develop 12 --checkout
Mark a draft ready, or make it a draft again	src pr ready 7, src pr ready 7 --undo
Revert a merged pull request, or bring the base branch into one	src pr revert 7, src pr update-branch 7 --rebase
Lock the conversation of a pull request	src pr lock 7, src pr unlock 7

• A lock reason is off_topic, resolved, spam or too_heated.
• src never asks a question. So the commands that delete, archive or rename need --yes.

Later: repositories#

You want to	Command
Pick the repository that src uses in this clone	src repo set-default acme/app
Update a fork from its parent, or your clone from its remote	src repo sync acme-fork/app, src repo sync
Rename, archive or delete a repository	src repo rename app2 --yes, src repo archive --yes, src repo delete acme/old --yes
Link text like JIRA-123 to another tool	src repo autolink create JIRA- "https://jira.example.com/browse/JIRA-<num>"
Find a gitignore or license template	src repo gitignore list, src repo license list
Copy labels, find repositories, list your organizations	src label clone acme/app, src search repos cli --owner acme, src org list

Later: CI from the terminal#

gh's run, workflow, cache, secret and variable commands work on the CI of the forge.

You want to	Command
See the runs, and watch one until it ends	src run list, src run watch <run>
Read the log of the failed steps	src run view <run> --log-failed
Start a workflow, or turn one off	src workflow run deploy.ts -f env=staging, src workflow disable nightly.ts
Set a secret or a variable	src secret set NPM_TOKEN --host registry.npmjs.org < token.txt, src variable set REGION --body eu-west
Give a task to an agent	src agent-task create "Fix the flaky login test" -a <agent>

• A workflow is its file name, like nightly.ts, or its name.
• src agent-task create needs -a, because the forge has no default agent.
• The CI reference has every flag. CI variables shows how a job reads a variable.

Later: shell completion#

Press Tab to complete the commands and the flags of src. Add one line to the startup file of your shell:

Shell	Add this line	To
bash	eval "$(src completion -s bash)"	~/.bashrc
zsh	source <(src completion -s zsh)	~/.zshrc, after compinit
PowerShell	Invoke-Expression -Command $(src completion -s powershell | Out-String)	$PROFILE

In fish, save the script once:

src completion -s fish > ~/.config/fish/completions/src.fish

The script holds the commands of the src that made it. After you upgrade src, save the fish file again.

Later: your gh aliases and settings#

src keeps aliases and settings in gh's format. The file is config.yml in ~/.config/src on macOS and Linux, and in %APPDATA%\src on Windows.

Copy your gh aliases into src:

command gh alias list | src alias import -
src alias list

In PowerShell, run gh.exe alias list | src alias import -.

Make a new alias:

src alias set bugs 'issue list --label bug'
src bugs

• $1, $2 and so on in an alias take the arguments after the alias name.
• --shell runs the alias through sh, as gh does.
• src refuses an alias whose name is a src command, or whose command src does not have. To change an alias, add --clobber.
• src config get, set and list read and write gh's settings, with gh's keys. src acts only on the aliases now.

Later: several accounts#

You have a work account and a personal account on the same forge. src keeps both logins, and uses one at a time.

src auth login
src auth switch

1. Run src auth login again, and approve with the other account. That account is now active.
2. To go back, run src auth switch. With two accounts on a host, it picks the other one.

• If you have more accounts or more hosts, name the account: src auth switch --user <name> --hostname <host>.
• src auth refresh runs the browser login again for the active account, and keeps the new token.
• src auth logout --user <name> forgets one account.
• While SRC_TOKEN is set, src uses it. Then auth switch and auth refresh stop with an error.

Later: gh commands that src does not have#

These gh commands will not come to src. When you run one, src prints the reason and exits with 1.

gh command	Why
codespace	TanStack Source has no codespaces or other hosted dev environments.
extension	src has no extension system, so it does not install or run gh extensions.
copilot	TanStack Source does not have GitHub Copilot.
attestation	TanStack Source does not make build provenance attestations.
ssh-key, repo deploy-key	git on TanStack Source takes tokens only, and the forge serves no SSH.
gpg-key	TanStack Source does not check commit signatures, so an account has no GPG keys.

Other gh commands, such as release and gist, are not supported yet. src help support lists each command and flag, and tells you whether it works now. The support page has the same list.

Later: skills#

src skill has the install, list, preview, publish, search and update commands of gh skill, for skills on the forge:

src skill search "write e2e tests"
src skill install acme/changelog
src skill update --all

It also has commands that gh does not have, such as add-to-repo, update-in-repo, create, share and suggest. See Add a skill to your agents and Add skills to a repository.

Later: MCP servers#

gh has no commands for these. src mcp connects remote MCP servers to the factory agents of a repository, and writes them into the config of your local agents. Without -R, a command acts on the repository of your clone. 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

• connect reads the header values from standard input, one line for each --header, in order. A value never goes into your shell history. Here key.txt holds the full value, for example Bearer lin_api_....
• A server that signs in with OAuth needs a browser. For such a listing, connect prints the web page that connects it.
• See Use the servers in your local agent for src mcp pull.

Later: monorepos#

gh has no commands for these. 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, status and pr create at the root of the checkout.
• member add takes --folder for a folder other than the name of the repository.
• Without -R, the member commands act on the repository of your clone.

See Clone and sync a monorepo and Change several members in one pull request.

Later: scripts and CI#

A script or a CI job has no browser. Give it a token:

1. Make a personal access token in Settings, Tokens. Make an access token shows the form.
2. Give the token to the job as SRC_TOKEN.
3. Run src with no login step.

src sends SRC_TOKEN only to its default host. Set SRC_HOST (for example localhost:5173) to use another forge. src never reads GH_TOKEN or GITHUB_TOKEN, so your GitHub token never goes to the forge.

A token that is limited to repositories cannot do account-level work, such as src auth status.

To get only the fields that your script needs, as JSON or as text, see Use src in scripts and agents.

Later: ask for a token from the terminal#

src token create asks for a token that works only on some repositories, with some actions, until its end time. You approve it in the browser. It needs no login, so an agent can run it. gh has no such command.

TOKEN=$(src token create -R acme/app --write --expires 2h)

Flag	What it does
-R, --repo	A repository that the token works on. Required. Repeat it for more repositories, all on one host.
--read	Asks for the read actions. This is the default without --write or --action.
--write	Asks for the read and write actions.
--action	Adds one action, for example vault:read. Repeat it for more. Without --read or --write, the token gets only these actions.
--expires	How long the token lives: 30m, 2h, 7d, at most 365d. The default is 1h.

• --name sets the name of the token. The default is src token on and the name of your computer.
• The token goes to stdout only. The code and the URL go to stderr.

See Let your agent ask for a token for the approval in the browser.

Later: architecture and impact#

gh has no commands for these. Without -R, a command acts on the repository of your clone.

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

• src pr impact also 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.

Later: the factory and bans#

gh has no commands for these. src factory runs the software factory, and src ban manages bans. Without -R, a command acts on the repository of your clone. With --org <name>, the settings, keys and ban commands act on an organization.

You want to	Command
See the factory settings	src factory settings
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
See the runs on an issue or a pull request	src factory runs 12
See the repository's newest runs (write access)	src factory runs -L 20
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
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>

• set-key reads the key from standard input, so the key does not go into your shell history.
• src factory keys lists the providers that have a key. It never shows a key.
• src factory agents prints the errors of the custom agent files on stderr, and exits 0. See Fix an error in the file.
• src ban suggestions lists the open suggested bans. Add --state banned or --state dismissed for the decided ones.
• A change file holds only the fields that you change. The security audit (audit), architecture and impact are on by default. Every other agent is off by default. For example, {"agents": {"value": {"enabled": true}}} turns the value check on.