Use the custdctl Client
custdctl is the command line client for Custd. It is a single binary: no Go
toolchain, no repository, no runtime to install. It signs in as you, including
system administrators and tenant members. The API enforces your permissions and
tenant scope, just as it does for the UI and SDK. The CLI is not a separate
permission boundary.
Before you start
You need:
- a Custd account with permission to perform the operations you need.
The built-in prod profile uses Custd's shared public CLI client. You do not
need to register a client or obtain a client secret to sign in. Tenant-specific
CLI clients are optional; use one only when your administrator has supplied
that configuration.
Install the client
The fastest path is the console: open Admin → Credentials and use the Install custdctl card. It offers the binary for the machine you are on and the published checksum, and the download itself needs nothing from Custd.
Without a console session, take the same files from the Custd downloads repository.
Both paths serve the same four artifacts. The console links the stable names below, which always resolve to the newest release:
| Platform | Stable asset |
|---|---|
| Windows 64-bit | custdctl-windows-amd64.exe |
| macOS Apple Silicon | custdctl-darwin-arm64 |
| Linux 64-bit x86 | custdctl-linux-amd64 |
| Linux 64-bit ARM | custdctl-linux-arm64 |
Every release also carries the version-stamped copy of each one
(custdctl_<version>_<os>_<arch>) when you would rather pin a release than
take the newest. SHA256SUMS lists both names for every artifact, so whichever
file you downloaded has a line to verify against.
Windows
- Download
custdctl-windows-amd64.exe. - Verify it against
SHA256SUMS— on Windows:Get-FileHash -Algorithm SHA256 .\custdctl-windows-amd64.exe. - Move the binary to a folder on your
PATH, for exampleC:\Program Files\Custd\, and rename it tocustdctl.exe. - Open a new terminal so the new
PATHentry is visible.
macOS
- Download
custdctl-darwin-arm64. macOS requires Apple Silicon; Intel Macs are not supported. - Verify it against
SHA256SUMS:shasum -a 256 custdctl-darwin-arm64and compare the value with the matching line in that manifest. - Move the binary into
/usr/local/binand make it executable:sudo mv custdctl-darwin-arm64 /usr/local/bin/custdctl && sudo chmod +x /usr/local/bin/custdctl. - If macOS blocks the first run because the binary is not notarised, approve it
once in System Settings → Privacy & Security, or clear the quarantine
attribute with
xattr -d com.apple.quarantine /usr/local/bin/custdctl.
Linux
- Download
custdctl-linux-amd64(orcustdctl-linux-arm64). - Verify it against
SHA256SUMS:sha256sum custdctl-linux-amd64and compare the value with the matching line in that manifest. - Move the binary into
/usr/local/binand make it executable:sudo mv custdctl-linux-amd64 /usr/local/bin/custdctl && sudo chmod +x /usr/local/bin/custdctl.
Check the install at any time:
custdctl version
It prints the build facts of the binary: the version, the commit it was built
from, the build time and the Go version. The commit is what identifies a
build — quote it in a support message. The same facts appear in
custdctl system about --json.
Sign in to Custd
For the public Custd deployment, use the built-in profile:
custdctl login --profile prod
Choose browser login on this computer or device-code login using another browser. Both methods sign in your account; neither requires a tenant-specific client.
Optional: configure another deployment or tenant-specific client
Run the config init line your administrator gave you. It carries your API
URL, your identity provider issuer, your client id, your audience and your
scopes, and the profile name the client will use — which is your client id:
custdctl config init --profile "acme-cli" --api-url "https://custd.com" --issuer-url "https://auth.custd.com/" --client-id "acme-cli" --audience "custd" --scope "openid profile offline_access admin producers.provision"
The issuer must exactly match the server's discovery metadata, including the
trailing slash. The public Custd issuer is https://auth.custd.com/.
The public API base is https://custd.com, as configured by the production chart.
Copy it as it is. If you would rather set it up yourself, custdctl config init --help lists every flag.
The client stores this profile and the token it obtains on your machine, readable only by your own account:
| Platform | Location |
|---|---|
| Windows | %AppData%\custd\config.yaml and %AppData%\custd\tokens.json |
| macOS and Linux | $XDG_CONFIG_HOME/custd/, or ~/.config/custd/, holding config.yaml and tokens.json |
custdctl config path prints the path the client is using.
Sign in
custdctl login --profile prod
Naming the profile with --profile skips profile selection. Without it, a terminal
lists the profiles on this machine — the built-in prod and local, any you
added, and the one you last selected — and the arrow keys pick one, starting on
the profile a plain command would use, which is prod on a fresh machine. A
command that is piped, run from a script, or given CUSTD_PROFILE never asks: it
uses the profile you named or the stored one.
The client opens your browser, you sign in with your Custd account, and the browser hands the token back to the client. If no browser opens, the client prints a URL to paste into any browser yourself.
If your machine has no browser — a server, a container, a locked-down desktop — use the device-code flow instead:
custdctl login --profile prod --method device
It prints a URL and an eight-character code in two groups of four. Open the URL on
any device, enter the characters as shown, and complete sign-in and approval
in the browser. The plain Copy: line is suitable for copying. Codes are issued
in one upper-case alphabet that leaves out the characters people confuse when
reading aloud, and the page and the client fold what you type, so HQVS JNRU,
hqvs-jnru and hqvsjnru all reach the same code.
Use the verification URL printed by the CLI. Shared first-party login resolves your
account's memberships; it does not restrict you to the deployment's operator company.
An optional tenant-specific entry also exists at
https://auth.example.com/t/<your-company>/device?client_id=<your-client> for registered
tenant-bound clients. It is not required for the built-in prod profile.
The code is short-lived. If the page refuses it, or the client stops waiting because
the code expired, run custdctl login again: a pending code belongs to the sign-in
that created it and cannot be revived, so restarting the command is the whole
recovery. Nothing needs clearing locally, and no support step is involved.
Check who you are signed in as:
custdctl account
Sign out again with custdctl logout --profile prod.
Review an external application's access
When someone first connects an external application, Custd creates its access request automatically. A tenant administrator reviews it under Credentials → External application access in the console, or with the equivalent client commands. Nobody needs to register a client ID, enable a resource, or copy a secret for this flow.
custdctl auth clients admissions list --profile acme-cli
custdctl auth clients admissions review --profile acme-cli \
--admission-uuid <request-uuid> --output application-review.json
Review the displayed application name, metadata-document URL, redirects and requested permissions. The file records that exact snapshot; choose a new filename when reviewing again rather than overwriting it. If you approve that access:
custdctl auth clients admissions approve --profile acme-cli --file application-review.json
Approval sends only the reviewed snapshot. If the request changed, the command refuses it: review again
before approving the new permissions. An unchanged approved application needs no administrator present
for later sign-ins. Tenant selection defaults to your signed-in company; a platform operator must explicitly
supply --company-slug when listing or reviewing a company's requests.
To withdraw approval:
custdctl auth clients admissions revoke --profile acme-cli \
--admission-uuid <request-uuid> --confirm
Revocation blocks new grants and refreshes. Access tokens already issued remain valid until they expire. An application never gains platform authority merely because a platform administrator signed in.
Find the command you need
custdctl --help lists every command, grouped into Your tenant and
Platform operator. The grouping is the authority the command needs: a
command under Platform operator is refused for a tenant administrator.
custdctl commands
prints the same inventory for your tenant, with a description beside every command, so you can search for the verb you want:
custdctl commands | grep -i rotate
Every command explains itself:
custdctl sites rotate-write-key --help
custdctl help sites rotate-write-key
Both print the same block: what the command does, which flags it requires, every
flag with a description, and one working example. A wrong flag is reported with
the flag that was not understood and the exit code 2.
Get output you can pipe
Every command that produces data emits exactly one JSON document, so it pipes
straight into jq:
custdctl account --json | jq -r '.email'
custdctl usage me --json | jq '.data.rows[] | {meter: .meterSlug, quantity}'
The request identifier travels inside the document, so you can quote it in a support message.
When something goes wrong
These answer the first questions of any support conversation:
custdctl diagnose
custdctl system about --json
custdctl system diagnostics capture --tenant-scope --output ./custd-evidence
custdctl diagnose is the one that reports reachability: it separates a
network problem from an authorization one (api_reachable=true but
api_authorized=false means the credential is the problem, not the network).
system about --json reports the build the binary was made from.
system diagnostics capture --tenant-scope writes a bounded, redacted evidence
bundle for your tenant.
The system-wide capture needs platform authority and is refused for a tenant administrator. That refusal is intentional: a tenant cannot read another tenant's state.
Send the two outputs to your Custd contact. The evidence bundle contains no event payloads, no credentials and no other tenant's data.
What the client cannot do
The client is a thin shell over the same contract your SDK uses. It does not grant authority: a command is refused when your account lacks the role, and the CLI has no way around that. Anything that needs platform authority — operating the platform, running maintenance commands, reading another tenant — is out of scope for a tenant administrator by design.