portald-agent-cli

CLI for registering AI agents with Portald - the authorization infrastructure for autonomous AI agents.

Installation

# Via npm (when published)
npm install -g portald-agent-cli

# Or run directly with npx
npx portald-agent-cli pair --code <CODE> --server https://portald.ai

# Or clone and link locally
git clone https://github.com/portald/portald-agent-cli
cd portald-agent-cli
npm install
npm run build
npm link

Usage

portald-agent <command> [options]

Commands

pair - Register with a Portald server

portald-agent pair --code <PAIRING_CODE> [--server <URL>]

Registers this agent with a Portald server using a pairing code. The code is generated by a human user in the Portald dashboard.

The CLI will:

1. Generate an Ed25519 keypair (stored in ~/.portald/agent.key)
2. Submit the pairing code and public key to the server
3. Sign a challenge to prove key ownership
4. Poll for approval status

status - Check approval status

portald-agent status [--server <URL>]

Check if this agent has been approved by the human owner.

whoami - Show agent public key

portald-agent whoami

Display this agent's public key and key file location.

Options

| Option | Description | Default | |--------|-------------|---------| | --code <CODE> | Pairing code from Portald dashboard | (required for pair) | | --server <URL> | Portald server URL | https://portald.ai |

How It Works

1. Human generates pairing code: In the Portald dashboard, the user creates a pairing code (expires in 10 minutes)
2. Agent registers: The CLI sends the code + agent's public key to the server
3. Challenge-response: Server issues a cryptographic challenge; CLI signs it to prove key ownership
4. Human approves: The human reviews and approves the agent in the dashboard
5. Agent receives capability token: Once approved, the human shares a capability token with the agent

Key Storage

Agent keys are stored in ~/.portald/agent.key with restrictive permissions (0600).

{
  "publicKey": "base64url-encoded-ed25519-public-key",
  "privateKey": "base64url-encoded-ed25519-private-key"
}

Important: Keep your private key secure. Anyone with access to this key can act as your agent.

Integration

After pairing, agents use the capability token to submit actions to Portald:

const response = await fetch('https://portald.ai/api/agent-actions/ingest', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${capabilityToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    action_type: 'purchase',
    action_payload: { 
      amount_cents: 1999,
      description: 'Coffee subscription'
    },
    risk_level: 'low',
    idempotency_key: 'unique-action-id',
  }),
});

See the Portald SDK documentation for more details.

License

MIT