CLI Reference

Complete reference for the Alien Agent ID command-line tool. All commands are run via node cli.mjs <command>.

Commands

`bootstrap`

One-command setup: generates keypair, starts OIDC auth, waits for human approval, creates owner binding, and configures git signing.


node cli.mjs bootstrap

Blocking: Yes (up to 5 minutes while waiting for QR scan)

Returns "alreadyBootstrapped": true if already set up.

`status`

Check if Alien Agent ID exists and is bound to a human owner.


node cli.mjs status

Returns JSON with bound, fingerprint, and owner fields.

`init`

Generate an Ed25519 keypair without starting the auth flow.


node cli.mjs init

`auth`

Start OIDC authorization and get a QR code / deep link for human approval.


node cli.mjs auth --provider-address <addr>

Returns JSON with deepLink, qrCode, pollingCode, and expiredAt.

`bind`

Poll for human approval and create the cryptographic owner binding.


node cli.mjs bind [--timeout-sec 300]

Blocking: Yes (up to --timeout-sec, default 5 minutes)

`git-setup`

Configure git SSH signing with the agent’s key.


node cli.mjs git-setup [--global] [--email user@example.com] [--name Agent]

Flag	Description
`--global`	Apply git config globally instead of per-repo
`--email <email>`	Git committer email (should match GitHub account)
`--name <name>`	Git committer name (default: `Agent`)

`git-commit`

Create a signed commit with provenance trailers, audit log entry, and proof note.


node cli.mjs git-commit --message "feat: implement feature" [--push]

Flag	Description
`--message <msg>`	Commit message (required)
`--push`	Push commit and proof notes to remote
`--remote <name>`	Remote to push to (default: `origin`)
`--allow-empty`	Allow empty commits

`git-verify`

Verify the provenance chain of a commit.


node cli.mjs git-verify [--commit HEAD]

Traces: SSH signature → agent key → owner binding → SSO attestation.

`auth-header`

Generate a signed authentication token for service calls.


# JSON output
node cli.mjs auth-header
 
# Raw header for curl
node cli.mjs auth-header --raw

Token is valid for 5 minutes.

`vault-store`

Store an encrypted credential in the vault.


# From file (most secure)
node cli.mjs vault-store --service github --type api-key --credential-file /tmp/tok
 
# From environment variable
node cli.mjs vault-store --service github --type api-key --credential-env GITHUB_TOKEN
 
# From stdin
echo 'ghp_xxx' | node cli.mjs vault-store --service github --type api-key
 
# Direct (least secure — visible in ps)
node cli.mjs vault-store --service github --type api-key --credential "ghp_xxx"

Flag	Description
`--service <name>`	Service identifier (required)
`--type <type>`	Credential type: `api-key`, `password`, `oauth`, `bearer`, `custom` (default: `api-key`)
`--credential <value>`	Credential value (least secure method)
`--credential-file <path>`	Read credential from file
`--credential-env <var>`	Read credential from environment variable
`--username <user>`	Associated username
`--url <url>`	Associated service URL

`vault-get`

Retrieve a decrypted credential from the vault.


node cli.mjs vault-get --service github

Returns JSON with service, type, credential, url, and username.

`vault-list`

List all stored credentials without decrypting values.


node cli.mjs vault-list

`vault-remove`

Remove a credential from the vault.


node cli.mjs vault-remove --service github

`sign`

Sign an operation for the audit trail.


node cli.mjs sign --type TOOL_CALL --action "bash.exec" --payload '{"command":"deploy"}'

Flag	Description
`--type <type>`	Operation type (e.g., `TOOL_CALL`, `API_CALL`)
`--action <action>`	Action identifier
`--payload <json>`	JSON payload to sign

`verify`

Verify state chain integrity.


node cli.mjs verify

`export-proof`

Export proof bundle to stdout (base64url-encoded JSON).


node cli.mjs export-proof

The proof bundle contains the agent’s public key, owner binding, id_token, and SSO base URL. Anyone with this bundle can verify the full provenance chain.

Common Flags

These flags apply to most commands:

Flag	Default	Description
`--state-dir <path>`	`~/.agent-id`	State directory
`--provider-address <addr>`	—	Alien provider address
`--sso-url <url>`	`https://sso.alien-api.com`	SSO base URL
`--oidc-origin <origin>`	`http://localhost`	OIDC redirect origin

Environment Variables

Variable	Purpose
`AGENT_ID_STATE_DIR`	Custom state directory (default: `~/.agent-id`)
`ALIEN_PROVIDER_ADDRESS`	Provider address (avoids `--provider-address` flag)

Provider Address Resolution

The provider address is resolved in this order:

--provider-address <addr> flag
ALIEN_PROVIDER_ADDRESS environment variable
default-provider.txt file next to the CLI

Error Reference

Error	Action
`No provider address`	Set `--provider-address`, env var, or `default-provider.txt`
`No pending auth found`	Run `auth` or `bootstrap`
`Alien SSO authorization session expired`	Run `bootstrap` again
`User rejected Alien SSO authorization`	Ask user to try again
`Timed out waiting`	Run `bootstrap` again, remind user to scan promptly
`No agent keypair`	Run `bootstrap` or `init`
`No credential stored for "..."`	Ask user for the credential, then `vault-store`