# amfelt register

Register this agent with your organization.

Register this agent with the Amfelt platform.

Performs a one-shot registration using a short registration code issued
when the agent is invited. On success, writes three identity files so
subsequent startups skip registration, and the endpoint they belong to:

```text
  ~/.amfelt/agent-keys/id_ed25519    Ed25519 private key (PEM)
  ~/.amfelt/agent.id                 agent UUID
  ~/.amfelt/agent.org                organization UUID
  ~/.amfelt/agent.endpoint           API endpoint registered with
```

Agent state has two roots, and this command writes to the identity one:

```text
  identity    $AMFELT_DIR, or ~/.amfelt when unset. Holds the four files
              above plus projects.yaml. Only the environment variable moves
              this root; --amfelt-dir does not.
  workspace   --amfelt-dir, else $AMFELT_DIR, else the workspace setting
              in the config file, else .amfelt. Holds downloaded plugins, cached assets,
              and deployed project files. A relative value resolves against
              the current working directory, so by default these land in
              ./.amfelt: run the agent from /opt/myapp and its plugins are
              in /opt/myapp/.amfelt, not under your home directory.
```

Exporting `$AMFELT_DIR` as an absolute path, and not passing `--amfelt-dir`,
collapses the two onto one directory. The approval record written by
`--wait-for-approval` is the exception — it always goes to
~/.amfelt/agent.status, whatever `$AMFELT_DIR` says.

The AMFELT_AGENT_*_PATH variables below override individual identity files.

If the invite was created with approval_required=true, the agent will be in
"pending_approval" status after registration. Pass `--wait-for-approval` to
block until an administrator approves (or rejects) the agent.

The API endpoint register uses is the first of: `--api-url`,
`$AMFELT_SECRET_API_URL`, secret.api_url in the config file,
`$AMFELT_API_ENDPOINT`, api-endpoint in the config file, the endpoint
remembered from an earlier registration, and https://api.amfelt.com.
Only a first registration may use that default: one that finds no
identity file, not even part of an identity, in `$AMFELT_DIR`, in
~/.amfelt, or at an AMFELT_AGENT_*_PATH. To register again over an
identity whose endpoint is not remembered, pass `--api-url` or set
`$AMFELT_API_ENDPOINT`. Register prints the endpoint, and where it came
from, before it sends anything, and after a successful registration
remembers it in agent.endpoint beside agent.id. The identity is bound to
the endpoint it registered with, so the later commands never fall back
to the default: with no endpoint configured, they use the one remembered beside the identity.
Name an endpoint only for an on-premises control plane, a demo or a
test.

```text
Environment variables:
  AMFELT_AGENT_REGISTRATION_CODE     One-time code from the agent invite (e.g., XSR-45W)
  AMFELT_API_ENDPOINT                Amfelt API base URL (optional, see above)
```

Per ADR-VaultThroughAPI (C38) the agent never contacts the secret
store directly; the API server handles that hop. Setting
AMFELT_INFISICAL_URL on the agent host is a startup error — unset
the variable and redeploy.

```text
Optional:
  AMFELT_AGENT_KEY_PATH   Override key file location
  AMFELT_AGENT_ID_PATH    Override agent-id file location
  AMFELT_AGENT_ORG_PATH   Override org-id file location
```

## Usage

```text
amfelt register [flags]
```

## Flags

| Flag | Type | Default | Description |
| --- | --- | --- | --- |
| `--api-url` | `string` | — | API base URL — overrides the variables, the config file, the remembered endpoint and the default https://api.amfelt.com |
| `-c`, `--code` | `string` | — | One-time code from the agent invite (e.g., XSR-45W) |
| `--force` | `bool` | `false` | Replace an existing identity. Without it, registering with a code into a directory that already holds an identity is refused rather than silently ignored |
| `--poll-interval` | `duration` | `5s` | Seconds between status polls when waiting for approval |
| `--timeout` | `duration` | `15m0s` | Max time to wait when `--wait-for-approval` is set |
| `-w`, `--wait-for-approval` | `bool` | `false` | Block until the agent is approved (default: return immediately after register) |
{.clidoc-flags-table}

## Global flags

| Flag | Type | Default | Description |
| --- | --- | --- | --- |
| `--amfelt-dir` | `string` | `.amfelt` | directory for workspace files (such as plugins); does not move agent identity (controlled by AMFELT_DIR) |
| `--config` | `string` | — | directory or filename of the application configuration |
| `-f`, `--format` | `string` | `default` | log format to use; either default, pretty, or json |
| `-l`, `--level` | `string` | `info` | minimum log level to display; either error, warn, info, or debug |
| `-v`, `--verbose` | `bool` | `false` | trigger to use verbose logging |
{.clidoc-flags-table}

---

Generated from `amfelt` v5.6.3.