Skip to main content

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:

PlatformStable asset
Windows 64-bitcustdctl-windows-amd64.exe
macOS Apple Siliconcustdctl-darwin-arm64
Linux 64-bit x86custdctl-linux-amd64
Linux 64-bit ARMcustdctl-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​

  1. Download custdctl-windows-amd64.exe.
  2. Verify it against SHA256SUMS — on Windows: Get-FileHash -Algorithm SHA256 .\custdctl-windows-amd64.exe.
  3. Move the binary to a folder on your PATH, for example C:\Program Files\Custd\, and rename it to custdctl.exe.
  4. Open a new terminal so the new PATH entry is visible.

macOS​

  1. Download custdctl-darwin-arm64. macOS requires Apple Silicon; Intel Macs are not supported.
  2. Verify it against SHA256SUMS: shasum -a 256 custdctl-darwin-arm64 and compare the value with the matching line in that manifest.
  3. Move the binary into /usr/local/bin and make it executable: sudo mv custdctl-darwin-arm64 /usr/local/bin/custdctl && sudo chmod +x /usr/local/bin/custdctl.
  4. 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​

  1. Download custdctl-linux-amd64 (or custdctl-linux-arm64).
  2. Verify it against SHA256SUMS: sha256sum custdctl-linux-amd64 and compare the value with the matching line in that manifest.
  3. Move the binary into /usr/local/bin and 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:

PlatformLocation
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.