The Bitaic CLI lets DevOps, platform, operations, and automation teams install agents, inspect agent state, run manual monitoring checks, and retrieve selected monitoring data from a terminal or script.
What You Can Do
The Bitaic CLI provides a terminal workflow for installing agents, checking installed versions, starting and stopping collectors, running manual checks, and retrieving current status for monitored resources.
Install And Authenticate
Install the Bitaic CLI from Bitaic Downloads using the macOS/Linux shell installer, Windows PowerShell installer, or a signed artifact for managed deployment.
Use the self-contained CLI binary. Python is not required for installation, authentication, agent management, or normal CLI use.
Verify the installed CLI with bitaic version.
Sign in with browser-based login for interactive terminals, or use device-code login when the host cannot open a browser.
Use workspace-scoped profiles to switch between Bitaic workspaces without moving credentials into scripts or committed config files.
Authentication And Profiles
Interactive CLI sessions use a Bitaic login flow tied to a workspace profile. The profile stores non-secret workspace metadata in a per-user config file, while access credentials stay in OS credential storage when available.
bitaic login
bitaic auth status
bitaic profile list
bitaic profile use production
Use case
Auth method
Credential handling
Typical permission
Interactive terminal
Browser login, or bitaic login --device on headless hosts.
Store tokens in macOS Keychain, Windows Credential Manager, or Linux Secret Service/libsecret when available.
Viewer, Operator, or Admin based on the commands used.
Automation and CI
Workspace-scoped service token.
Provide BITAIC_TOKEN, BITAIC_WORKSPACE, and optional BITAIC_PROFILE from a secrets manager.
Least-privilege token scopes for the automation task.
Multiple workspaces
Named CLI profiles.
Keep profile metadata in ~/.config/bitaic/config.yml on macOS/Linux or %APPDATA%\Bitaic\config.yml on Windows.
The active profile's workspace role or token scopes.
Command Contract
Public-release CLI commands use the form bitaic <group> <action> [resource] [flags]. Public command groups are auth, profile, install, agent, endpoint, ssl, domain, dns, and update, with top-level help, version, login, and logout commands. Private-beta Health Monitoring and Windows Event Monitoring commands are listed separately for enrolled workspaces.
Flag
Scope
Behavior
--profile <name>
Workspace-aware commands.
Use the named CLI profile for this command.
--workspace <workspace_id_or_slug>
Login, automation, and workspace-aware commands.
Select or override the workspace where supported.
--config <path>
Commands that read CLI or agent configuration.
Read configuration from a non-default path.
--output text|json
Commands with structured output.
Use human-readable text by default or JSON with the same field names for automation.
--no-color
Text output.
Disable terminal color for logs and CI output.
--help
Any command.
Show help for the selected command.
--version
Top-level CLI.
Show the installed CLI version.
Command Summary
Command
Purpose
Arguments
Expected output
Related docs
bitaic help
Display CLI help and available command groups.
Optional command name or group.
Help text and command list.
CLI reference.
bitaic version
Show the installed CLI version.
None.
CLI version string.
CLI installation.
bitaic login
Start browser-based CLI authentication.
Optional workspace or profile selection.
Authenticated profile and active workspace.
CLI authentication.
bitaic login --device
Authenticate on a host that cannot open a browser.
Device-code flag and optional workspace or profile selection.
Device code, verification URL, and authenticated profile.
CLI authentication.
bitaic auth status
Show the current CLI authentication state.
Optional profile name.
Active profile, workspace, role, and token-expiration state.
CLI authentication.
bitaic profile list
List configured workspace profiles.
None.
Profile names, workspace IDs or slugs, and active marker.
The examples below show common public-release CLI output shapes for version checks, agent installation, agent status, manual endpoint checks, product checks, and agent updates.
$ bitaic version
version: <installed-version>
$ bitaic auth status
profile: production
workspace: ops-production
role: Operator
status: authenticated
$ bitaic profile use staging
active_profile: staging
workspace: ops-staging
$ bitaic update agent all
status: complete
updated_agents:
- endpoint
next: bitaic agent version <agent_name>
Private Beta CLI Scope
Enrolled workspaces only
Health Monitoring and Windows Event Monitoring commands are private beta until Q1 2027 public-release planning. Keep their command output, configuration files, support paths, and automation examples scoped to beta workspaces until product owners approve public availability.
Private-beta product
CLI commands
Write boundary
Health Monitoring
bitaic install agent health, bitaic agent status health, bitaic health status.
Threshold writes stay in dashboard, API, or configuration workflows until product owners approve public CLI write commands.
Windows Event Monitoring
bitaic windows-events status [--host <host_name>], bitaic windows-events list [--host <host_name>] [--log <log_name>] [--level <level>] [--event-id <event_id>] [--since <timestamp_or_duration>].
Event rule writes stay in dashboard, API, or configuration workflows until product owners approve public CLI write commands.
Private-beta Health Monitoring status output uses these fields: host, os_family, os_version, architecture, agent_status, telemetry_state, agent_freshness_seconds, collection_interval_seconds, cpu_usage_percent, memory_usage_percent, disk_usage_percent, disk_read_bytes_per_second, disk_write_bytes_per_second, disk_io_utilization_percent, alert_state, checked_at.
$ bitaic windows-events list --host win-app-01 --log System --level error --since 1h
events:
- host: win-app-01
log: System
event_id: 7031
level: error
source: Service Control Manager
provider: Service Control Manager
event_time: 2026-08-25T14:21:08Z
event_state: matched
alert_state: warning
Private-beta input
Purpose
Notes
health-agent-config.yml
Stores private-beta Health Monitoring collection interval, local buffer duration, metric toggles, and threshold seeds for CPU, memory, disk usage, and disk I/O.
Use this file only for enrolled private-beta host metric collection inputs and initial Health threshold values.
windows-event-agent-config.yml
Stores private-beta Windows Event Monitoring collection mode, checkpoint cadence, local buffer limits, event filters, duplicate suppression, and event-rate rules.
Use this file only for enrolled private-beta Windows Event agent collection inputs when event rules are seeded from configuration.
Configuration And Environment
Input
Purpose
Notes
endpoint-agent-config.yml
Stores monitored endpoint URLs, request behavior, check cadence, timeouts, and SSL alert windows for endpoint and certificate workflows.
Use this file for endpoint and certificate check inputs.
update-agent-config.yml
Stores update workflow settings for installed agents.
Use this file for agent update behavior.
CLI auth profile
Connects CLI commands to the correct Bitaic workspace and default output behavior.
Stored in ~/.config/bitaic/config.yml on macOS/Linux or %APPDATA%\Bitaic\config.yml on Windows.
BITAIC_TOKEN
Supplies a workspace-scoped service token for noninteractive automation.
Source this value from a secrets manager or protected runtime variable, not from committed files.
BITAIC_WORKSPACE
Sets the workspace for service-token automation.
Use with BITAIC_TOKEN when a job does not rely on an interactive profile.
BITAIC_PROFILE
Selects a named CLI profile for a command or automation job.
Useful when one host has separate staging and production profiles.
Output, Status, And Exit Codes
CLI output uses snake_case field names, lowercase status labels, ISO-8601 UTC timestamps, and millisecond suffixes for latency or duration fields. JSON output uses the same fields as text output.
Invalid command usage, flag value, or config syntax.
Fix command syntax or configuration before retrying.
3
Authentication is missing, expired, or invalid.
Refresh login or service token.
4
Active user, profile, or token lacks permission.
Use a role or token scope that matches the command.
5
Requested profile, agent, target, or resource was not found.
Check names, workspace, profile, and installation state.
6
Command completed but the monitored result is unhealthy.
Alert or fail CI when the monitored state should be healthy.
7
Retryable network, API, or rate-limit failure remained.
Retry later and include request or support IDs if present.
8
The command timed out.
Check network path, target response time, and timeout settings.
Retry Behavior
Idempotent reads and checks may retry connection reset, DNS failure, TLS handshake failure, HTTP 408, HTTP 429, and HTTP 5xx responses.
Default retries use three attempts with jittered backoff of roughly 1s, 3s, and 10s.
Writes such as install, start, stop, logout, and profile changes do not retry by default unless the CLI can prove the previous attempt did not change state or the API supports an idempotency key.
Manual monitoring checks may retry transport failures, but they do not retry a successful check because the monitored target is down or degraded.
Errors And Recovery
Error pattern
Exit code
Likely cause
Recovery
Unknown command
2
The command or subcommand is not supported by this CLI build.
Run bitaic help and verify the installed version.
Authentication missing or expired
3
The CLI does not have a valid token or login session.
Run bitaic login or refresh the service token, then confirm the active profile with bitaic auth status.
Permission denied
4
The active workspace role or service token lacks the required permission.
Use Viewer for read-only checks, Operator for monitoring configuration, and Admin or API-access permissions for token, webhook, integration, user, role, or audit-log administration.
Agent is not installed
5
The requested agent is missing from the host.
Install the agent, then run bitaic agent status <agent_name>.
Agent is stopped or stale
6
The agent is not running or has not reported recently.
Start the agent, confirm host permissions, and review network access to Bitaic.
Configuration parse error
2
A YAML file has invalid syntax or unsupported fields.
Validate the relevant config file and remove unsupported fields.
Retryable network or API failure
7
The CLI exhausted retries for a transient network, API, or rate-limit response.
Retry later, check network access, and include request or support IDs if the output provides them.
Command timed out
8
The CLI did not receive a result before the timeout.
Check the network path, target response time, and timeout settings before retrying.
Monitoring target check fails
6
The endpoint, host, DNS record, or monitored target is failing.
Use the related product page to inspect expected data, threshold behavior, and troubleshooting steps.
Scripting And CI Use
Automation should use workspace-scoped service tokens from the runtime secret store rather than interactive user sessions. Treat any nonzero exit code as a reason to stop or alert. Exit code 6 means the command ran but found an unhealthy monitored state, while exit codes7 and 8 point to retry exhaustion or timeout. Log CLI output with secrets redacted so operators can troubleshoot agent state, authentication, and monitored target failures.
BITAIC_TOKEN=<token-from-secret-store>
BITAIC_WORKSPACE=ops-production
bitaic auth status
bitaic version
bitaic agent status endpoint
bitaic endpoint check https://your-domain.com