How should the keychain option be used for altool?

The way that worked for me was logging in with the Application Loader itself (check the "Keep me logged in" option) and use the keychain entry of the Application Loader.

So my command looks like this:

altool --validate-app -f APPLICATION.ipa -u my@apple.id -p @keychain:"Application Loader: my@apple.id"

Prerequisites:

• You need an Apple developer account, obviously. That's AC_USERNAME.
• You need a password for that account. If you can have two-factor authentication enabled, you need to create an app-specific password (beyond the scope of this answer). The password is AC_PASSWORD.
• The keychain item is going to need a name that is references via altool's @keychain parameter. We call this ITEM_NAME.

In the instructions below, replace AC_USERNAME, AC_PASSWORD and ITEM_NAME with the values you need. Do not type these names verbatim.

Now:

1. Create a generic password in your keychain.
   • You can do so via Keychain Access.app File > New Password Item … . In the Keychain Item Name, enter the name you want for ITEM_NAME, the Account Name is your AC_USERNAME and the AC_PASSWORD goes into the Password field.
   • Or you can do it via the command line: security add-generic-password -a "AC_USERNAME" -w "AC_PASSWORD" -s "ITEM_NAME"
2. In the arguments to altool, you now pass -u AC_USERNAME -p "@keychain:ITEM_NAME" to make it fetch the password from the keychain.
3. The first time you run altool, you get a security confirmation dialog asking you whether to allow altool to read the password. Enter your keychain password and click on Always allow.

To prevent the security confirmation dialog from appearing, either click on Always allow or modify the appropriate keychain entry. This works like this:

• Locate the path to altool by opening a shell and typing xcrun -find altool.
• Either use this path as argument -T <path> when creating the password using the security add-generic-password command or:
  • Open Keychain Access.app.
  • Select the password entry, select the menu File > Get Info (or press Cmd+I or click the ⓘ icon).
  • In this dialog, select the Access Control tab and press the + button. A file selection dialog opens.
  • Open Finder and select the menu Go > Go to Folder… and paste the path to altool (the directory part, without altool itself, e.g. /Applications/Xcode.app/Contents/Developer/usr/bin/).
  • Drag altool to the open panel of Keychain Access and press the Add button.

The correct usage is to enter the name of the keychain item (not the name of the keychain itself, and not the "Account" field for the keychain item).

My problem was actually related to access control. I had to edit the keychain item in Keychain Access and tweak the Access Control settings to allow altool to see the keychain item.