> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.itential.com/itential-gateway/5/iagctl/login/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server.

# iagctl login

Log in to the gateway server.

The `iagctl login` command authenticates a user with the gateway server from a client. After you log in, the gateway writes your API key to the `api.key` file in your gateway working directory. The gateway client automatically reads this file for subsequent API calls.

Always treat passwords and API keys with the utmost caution. Never share them with anyone.

For more information, see [Manage users and credentials](../manage-users-credentials).

## Syntax

```bash
iagctl login <username> [flags]
```

## Usage notes

### Initial login

The first time the server starts, it displays a temporary password for the `admin` user in the logs. When you log in with the `admin` user for the first time, the gateway requires you to change the password.

After authentication, the gateway server returns an API key with a default expiration time of 24 hours. You can change the expiration timeout on the server using the `GATEWAY_SERVER_API_KEY_EXPIRATION` configuration variable.

### Change a password

Use the `--change-password` flag to change your password. When you change a password, the gateway removes all previously created API keys for that user.

### Recover the admin account

If you lose the admin account credentials, run `iagctl server --recover-admin-user` on the server to start the reset process.

## Examples

### Log in

```bash
iagctl login jared
Enter password for user:
Successfully logged in!
```

### View the API key

Use the `--raw` flag to print the full API key to the terminal. This can be useful when using gateway commands in external applications:

```bash
iagctl login jared --raw

Enter password for user:
{
    "api_key": "AaJH5mic-BjShSjgqlSMj05DdJERcrLpudP-yJqEDvgwAOG"
}
```

### Change a password

```bash
iagctl login jared --change-password

Enter password for user:
Enter your NEW password to login:
Re-enter your NEW password for verification:
Password verified successfully!

Password was successfully reset!
Please login with the new password you just set.

Enter the NEW password for user:
Successfully logged in!
```

## Options

```bash
      --profile string   Specify the client profile to use (case-insensitive, defaults to [client] section)
  --change-password   Change the password for the user.
  -h, --help          Help for login
```

## Options inherited from parent commands

```bash
  --profile string   Specify the client profile to use (case-insensitive, defaults to [client] section)
  --config string   Path to the configuration file
  --raw             Display the result of the command in raw format
  --verbose         Enable verbose output
```