Hydrix Docs

CLI

Hydrix CLI command reference.

Use hydrix to authenticate, sync Hydrix Git credentials, operate organization repositories, and manage site lifecycle actions through the same Client Portal API permissions used by the web portal.

Install

  • Download the current release from Client Portal CLI downloads.
  • Run hydrix --version after installation.
  • Run hydrix help before first use.

Command Help

The installed binary is the authority for exact flags. Use command help before running any mutation, especially in automation or when you do not have repository access. 

hydrix help
hydrix help auth
hydrix help repos
hydrix help sites
hydrix auth login --help
hydrix repos create --help
hydrix sites create --help
hydrix sites help delete

Command Groups

Group Purpose Typical Use Safety Notes
auth Manage human auth, service-account auth, and Hydrix Git HTTPS credentials. Login, inspect current credential state, cache Git credentials, or log out. Do not put service-account tokens in shell history. Prefer --token-file -.
repos List, inspect, create, update, archive, or reactivate organization repository records. Prepare or maintain the repository binding used by Hydrix Git sites. The API exposes repository archival, not hard deletion.
sites List, inspect, create, deploy, enable, disable, delete, deregister, or bind site repos. Operate Hydrix sites through Client Portal API routes. Destructive actions require confirmation flags and matching credential grants.
version Print the installed CLI version. Confirm the installed binary before debugging command behavior. Use current help output when version behavior differs from examples.

Authentication

Human Login

  • hydrix auth login uses browser OAuth with PKCE.
  • hydrix auth login --password uses Cognito password auth.
  • Successful login attempts to cache Git credentials and configure Git author identity.

Service Account

  • hydrix auth service-account login --api <url> --token-file -
  • HYDRIX_CLI_SERVICE_ACCOUNT_TOKEN is accepted for non-interactive runners.
  • HYDRIX_SERVICE_ACCOUNT_TOKEN is also accepted for bot automation.

Git Sync

  • hydrix auth sync-git refreshes cached Hydrix Git HTTPS credentials.
  • Service accounts must pass --entity-id or --entity-ids.
  • Use hydrix auth status to confirm the active credential mode.

Configuration Sources

The CLI resolves settings from flags, environment variables, cached config, and discovery. Cached config is stored at ~/.hydrix/config.json.

Variable Purpose Example
HYDRIX_CLI_API_BASE_URL Client Portal API base URL. https://client.example.com/api
HYDRIX_CLI_CLIENT_ID Cognito app client id used for human login. <cognito-app-client-id>
HYDRIX_CLI_REGION AWS region for the Cognito user pool. us-east-1
HYDRIX_CLI_USER_POOL_DOMAIN Cognito hosted UI domain. <prefix>.auth.us-east-1.amazoncognito.com
HYDRIX_CLI_DISCOVERY_URL Explicit CLI discovery URL. https://client.example.com/.well-known/hydrix-cli.json
HYDRIX_CLI_CLIENT_PORTAL_DOMAIN Client portal host used to derive discovery when needed. client.example.com
HYDRIX_CLI_EMAIL Email for password-mode human login. user@example.com
HYDRIX_CLI_PASSWORD Password for non-interactive password-mode login. <password>
HYDRIX_CLI_SERVICE_ACCOUNT_TOKEN Service-account token for automation. hydrix_sa_...
HYDRIX_SERVICE_ACCOUNT_TOKEN Alternate service-account token variable for bot runners. hydrix_sa_...

Repository Commands

Command Purpose Example Notes
repos list List organization repositories. hydrix repos list --entity-id <entity-id> Supports provider, status, pagination, and sync flags.
repos get Fetch one repository record. hydrix repos get --entity-id <entity-id> <repo-id> Use before binding a site to confirm the repo id.
repos create Create repository metadata and, for Hydrix Git, optionally scaffold the remote repo. hydrix repos create --entity-id <entity-id> --repo-id storefront-web --url <url> Advanced requests can use --body or --file.
repos update Update repository provider, URL, default branch, or status. hydrix repos update --entity-id <entity-id> storefront-web --default-branch main At least one update field is required unless a raw body is supplied.
repos archive Set repository status to ARCHIVED. hydrix repos archive --entity-id <entity-id> storefront-web Use archival for removal workflows.
repos activate Restore an archived repository to ACTIVE. hydrix repos activate --entity-id <entity-id> storefront-web Use only when the repository should return to bind/deploy workflows.

Site Commands

Command Purpose Example Notes
sites list List sites visible to the active credential. hydrix sites list --entity-id <entity-id> Supports pagination with --limit and --start-key.
sites get Fetch one site record. hydrix sites get <site-id> Use before mutation to confirm the target site.
sites create Create a HYDRIX_GIT site from an organization repo binding. hydrix sites create --entity-id <entity-id> --site-name "Example" --domain example.com --repo-id storefront-web Advanced requests can use --body or --file.
sites deploy Queue a deployment for the current site source. hydrix sites deploy <site-id> --message "Release from CLI" Optional metadata includes --commit-id and --message.
sites enable Restore traffic and mail for a disabled site. hydrix sites enable <site-id> Confirm the site status before running.
sites disable Turn off traffic and mail without deleting infrastructure. hydrix sites disable <site-id> Confirm operator intent before running.
sites delete Queue full site teardown. hydrix sites delete <site-id> --yes Requires --yes and destructive access. Usage history is preserved.
sites deregister Remove a deleted site registration record. hydrix sites deregister <site-id> --yes Requires --yes. Usage history is not removed.
sites bind-repo Attach or update a site's repository binding. hydrix sites bind-repo <site-id> --repo-id storefront-web --ref main Supports --artifact-directory and --auto-deploy.
sites unbind-repo Remove a site's repository binding. hydrix sites unbind-repo <site-id> Confirm current deploy workflow before running.

Automation Guidance

  1. Start with LLM context, Hydrix discovery, and the OpenAPI index.
  2. Install or locate the hydrix binary. Do not assume source repository access.
  3. Run hydrix help and command-specific --help before selecting flags.
  4. Use service-account tokens from environment or stdin. Do not print or persist tokens in logs.
  5. Inspect hydrix auth status, target entity-id, target site-id, and target repo-id before mutation.
  6. Surface human approval requirements before destructive, billing, legal, domain-control, or ownership actions.

Useful Resources