How the CLI reaches Gitmoap
Overview
gitmoap and git-remote-gitmoap connect to Gitmoap on their own. There is nothing to configure: install them, run gitmoap login, and every command — and every git clone gitmoap://… — goes to the Gitmoap service.
The one address built into the tools is api.gitmoap.com. Everything else they need — where the API is, where git push connects, how to sign you in — they read from that address the first time they need it, and remember for a day. That is why an update on our side never needs a new install on yours.
The rest of this page is for when you want to look under the hood: what the tools resolved and from where, and the overrides that point them at another Gitmoap environment while you test something.
Before you start
- Both binaries on your
PATH.gitmoapruns the commands below;git-remote-gitmoapis what makesgitmoap://URLs work, and git finds it by name. - Outbound HTTPS to
api.gitmoap.com.The tools read their settings over the same connection they later use for the API. - No token, and no sign-in, to read settings.Every value on this page is public — they are what a client needs before it can authenticate, so none of them is a secret. Signing in comes after, with
gitmoap login, and needs a Gitmoap account — sign up at gitmoap.com.
How it works
Each setting is resolved on its own, from the first layer that supplies it:
- A command-line flag —
--host,--base-url,--profile. - An environment variable —
GITMOAP_HOST,GITMOAP_API_URL,GITMOAP_ENDPOINT, and one per setting below. git config gitmoap.endpointand friends, read by the remote helper only. Git runs it inside a repository, so a per-repository endpoint means something there; the CLI is not necessarily in one, and does not read them.- Your settings file,
~/.config/gitmoap/config.toml. - What Gitmoap publishes about itself, fetched from
https://api.gitmoap.com/.well-known/gitmoap-client-configand cached for 24 hours.
Layer 5 is the one that normally answers, and it is why a fresh install works. Layers 1–4 are overrides; you only reach for them to point the tools at another Gitmoap environment, and --host or GITMOAP_HOST changes which address layer 5 asks.
A client that already has every value it needs makes no such request. Pinning the endpoint by environment variable — the usual arrangement in a pipeline — means no lookup on any command.
How to
See what resolved, and from where
gitmoap doctorPrints every setting, the layer each came from, where your files are, whether you are signed in, and whether the API answers. This is the output to include when you contact support — it names the layer that produced each value, which is usually the whole diagnosis.
gitmoap config list prints the same settings table without the checks.
Re-read Gitmoap's published settings
Answers are cached for a day. To fetch fresh ones now:
gitmoap config refreshThe next command fetches fresh values.
Point the tools at another Gitmoap environment
When you are testing against an environment other than the Gitmoap service, give the tools its address for one command, for a shell, or for good:
gitmoap --host api.staging.example.com repos listGITMOAP_HOST=api.staging.example.com gitmoap repos listgitmoap config set host api.staging.example.comgitmoap login signs you in to whichever environment the tools are pointed at. gitmoap config unset host sends them back to Gitmoap.
Switch between environments with profiles
Settings live in named profiles, and one is the default:
default_profile = "gitmoap" [profiles.gitmoap] [profiles.staging]host = "api.staging.example.com"Pick one per command with --profile, or write to one with gitmoap config set --profile staging host api.staging.example.com. An empty profile reaches Gitmoap. Each profile keeps its own settings; the sign-in you hold is shared, so switching profiles between environments means signing in again.
Override a single setting
Any setting can be pinned without touching the others:
gitmoap --base-url https://api.staging.example.com repos listGITMOAP_API_URL=https://api.staging.example.com gitmoap repos listgitmoap config set api_url https://api.staging.example.comUse this when an environment publishes no settings, or when you need to reach one component through a different address than the one it advertises.
Configure a single repository
The remote helper reads git's own configuration, so one repository can talk to a different environment than the rest:
git config gitmoap.endpoint wss://wb.staging.example.comReference
Settings
| Setting | Environment variable | What it is |
|---|---|---|
host | GITMOAP_HOST | The address settings are read from, no scheme. api.gitmoap.com unless you override it. Everything below is looked up from it. |
api_url | GITMOAP_API_URL | Base URL of the API. GITMOAP_BASE_URL is also accepted. |
git_endpoint | GITMOAP_ENDPOINT | Where git push and git fetch connect. |
cognito_domain | GITMOAP_COGNITO_DOMAIN | The sign-in domain gitmoap login opens. |
cognito_region | GITMOAP_COGNITO_REGION | The region that sign-in domain lives in. |
cli_client_id | GITMOAP_CLI_CLIENT_ID | Identifies the CLI to the sign-in service. |
ca_bundle | GITMOAP_CA_BUNDLE | A PEM file of extra certificate authorities to trust. |
ca_bundle is the one setting Gitmoap can never supply, because a host that could name your certificate authorities could redirect the trust you place in it. Set it yourself or not at all.
Files
| File | Holds |
|---|---|
~/.config/gitmoap/config.toml | Your overrides and profiles. Absent until you set something. |
~/.config/gitmoap/credentials.json | Your sign-in, readable only by you. |
~/.config/gitmoap/discovery.json | Cached settings, one entry per address. Safe to delete. |
Set XDG_CONFIG_HOME to move all three. On Windows they live under %APPDATA%\gitmoap.
Commands
| Command | Does |
|---|---|
gitmoap config get <setting> | Prints one resolved value. Exits non-zero when there is none. |
gitmoap config set <setting> <value> | Writes it into the active profile. |
gitmoap config unset <setting> | Removes it from the active profile. |
gitmoap config list | Every setting with the layer it came from. |
gitmoap config path | The settings file's location. |
gitmoap config refresh | Forgets cached settings. |
gitmoap doctor | Settings, files, sign-in and reachability. |
Troubleshooting
could not reach Gitmoap at api.gitmoap.com
- Cause
- The tools could not fetch their settings — no network, a firewall or proxy blocking
api.gitmoap.com, or a DNS failure - What to do
- Check that
https://api.gitmoap.comopens from this machine, then re-run. If it does and the error persists, send the output ofgitmoap doctorto support@gitmoap.com
could not read Gitmoap's settings
- Cause
- The address answered, but not with settings — usually a
hostoverride naming the wrong address - What to do
- Check the
hostline ingitmoap doctor. If you did not mean to override it,gitmoap config unset host
A setting you changed keeps reverting
- Cause
- A higher layer is winning — an environment variable exported in another window is the usual one
- What to do
- Read the
fromline beside that setting ingitmoap doctorand unset whatever it names
A setting is stale but no layer explains it
- Cause
- The value came from a cached copy of the settings, which is kept for a day
- What to do
gitmoap config refresh, then re-run the command
git clone gitmoap://… fails saying the helper was not found
- Cause
git-remote-gitmoapis not on yourPATH. Git locates it by name, so renaming or moving it breaks the URL scheme- What to do
- Put the binary back on your
PATHunder its own name; do not rename it
Sign-in fails although the API answers
- Cause
- The sign-in settings and
api_urlresolved to different environments, usually because one is pinned by environment variable and the other is not - What to do
- Compare the two
fromlines ingitmoap doctorand make both name the same environment — or remove the overrides to reach Gitmoap
Certificate errors on every command, behind a company proxy
- Cause
- A proxy inspecting TLS presents its own certificate authority, which your machine trusts and this client does not
- What to do
- Point
ca_bundleat the proxy's PEM file:gitmoap config set ca_bundle /path/to/roots.pem
Related
- Install the command-line toolsgetting both binaries onto your machine.
- Access tokenssigning in from a script or a pipeline, where a token replaces the browser flow.
- Repositoriescloning and pushing once you are signed in.