alk command reference

This page documents every alk command, its arguments, and its options.

Note

This reference is a placeholder — it will be auto-generated from the CLI source in a future iteration.

Global options

Option	Description
--help, -h	Show help for any command.
--version, -v	Print the installed CLI version.
--yes, -y	Skip interactive confirmations. Use with care.
--dry-run	Show what would happen without making any changes.

Commands

alk setup

Initialises Alkaia in your AWS account by deploying the control-plane stack. Idempotent — safe to run multiple times.

alk whoami

Prints the AWS account ID and IAM identity Alkaia is using.

alk deploy <stack-file>

Deploys the application described by <stack-file> (a YAML file) to AWS.

alk validate

Checks that the Alkaia agent’s AWS footprint still matches what alk setup created — the agent is reachable, its IAM execution role still carries the alk:managed tag, the GitHub Actions OIDC Provider still exists, and (informationally) whether IAM Identity Center is configured. If everything checks out, it prints “Connection healthy” and exits 0. If something has drifted, it prints exactly which resource is affected and how to fix it, then exits 1.

Option	Description
--region <region>	Override the AWS region to validate against.
--endpoint <url>	Override the agent endpoint URL (useful before a config file exists).
--repair	Build a repair plan from whatever drift was found and, after you confirm it, fix what can be fixed automatically. See below for exactly what that covers.
--yes, -y	Skip the repair confirmation prompt (for scripted or CI use). Has no effect without --repair.
--dry-run	With --repair, print the repair plan and exit 0 without changing anything in AWS — no repair action runs, even with --yes.
--login <method>	Force sso or iam as the AWS login method if credentials need to be refreshed.
--no-login	Don’t launch an AWS login automatically when credentials are missing or expired.

What --repair fixes automatically:

• A missing or incorrect alk:managed=true tag on the agent’s IAM role — it re-applies the tag.
• A missing GitHub Actions OIDC Provider (token.actions.githubusercontent.com) — it recreates it with the same properties alk setup originally used.

What --repair always defers to alk setup: an agent that doesn’t respond to health checks, an agent IAM role that has been deleted entirely, and any check that fails because your AWS credentials can’t read the resource in question (a permissions problem, not drift). These are listed as “Needs you: …” steps rather than silently skipped or force-fixed — --repair never touches customer service infrastructure, never runs a CloudFormation operation, and never guesses at a fix it can’t verify is safe.

Flow: alk validate --repair always shows the plan first. Without --yes, it asks you to confirm before making any change; declining leaves everything untouched and exits 1. After running the automatic repairs (or immediately, if the plan was manual-only), it re-runs the full validation suite and prints the final result — the exit code (0 or 1) always reflects that final, real state, never an assumption that the repair worked. Every repair attempt is recorded in the audit log.

alk logs <service>

Prints the logs for one deployed service. Alkaia works out which logs to read from the stack, environment and service name — you never need to know where they live in AWS.

Option	Description
--env <name>, -e	Required. Which environment’s copy of the service to read.
--stack <name>, -s	Stack name. Defaults to the name in the alkaia.yaml in the current directory.
--file <path>	Path to the declaration file used to default the stack name (default alkaia.yaml).
--follow, -f	Keep printing new lines as they arrive, until you stop it with Ctrl-C.

If the service has no logs yet — it hasn’t been deployed, or hasn’t handled any traffic — alk logs says so and tells you what to check, rather than failing with an AWS error.

alk status

Shows what is currently deployed for a stack in one environment: each service, its public URL, and the state of the deployment that produced it (“Running — last deployed 2h ago”). When the last deploy failed, it says so and points you at alk deployments and alk logs.

Option	Description
--env <name>, -e	Required. Which environment to report on.
--stack <name>	Stack name. Defaults to the name in the local alkaia.yaml.
--file <path>	Path to the declaration file used to default the stack name (default alkaia.yaml).

alk deployments

Lists the deployment history for a stack in one environment, newest first: when each deploy ran, whether it worked, how long it took, and its outcome in plain language.

Option	Description
--env <name>, -e	Required. Which environment’s history to show.
--stack <name>	Stack name. Defaults to the name in the local alkaia.yaml.
--file <path>	Path to the declaration file used to default the stack name (default alkaia.yaml).
--limit <count>	How many deployments to show (1–100, default 20).

History starts when your agent was upgraded to a version that records it — deployments from before that are not listed.

alk teardown <stack-name>

Removes a deployed stack and all the AWS resources it created. Requires explicit destroy confirmation.