apes CLI

The apes CLI is your command-line gateway to an OpenApe IdP. It handles authentication, grant requests, delegations, and grant-secured command execution.

Ships alongside ape-shell, a drop-in shell replacement that routes every command through a DDISA grant — useful for sandboxing AI coding agents.

Installation

pnpm add -g @openape/apes
# or: npm install -g @openape/apes

After installation, verify:

apes --help
ape-shell --version

Quick Start

# Login (opens browser for PKCE flow)
apes login --idp https://id.example.com

# Verify identity
apes whoami

# Run a command through a grant
apes run -- git status

The first run creates a grant request. After a human approves it in the browser, the command executes.

Authentication Modes

Human (PKCE Browser Login)

apes login --idp https://id.example.com

Opens a browser for WebAuthn/passkey login. The token is stored at ~/.config/apes/auth.json.

Agent (Ed25519 Key)

For automated systems:

apes login \
  --idp https://id.example.com \
  --email agent@example.com \
  --key ~/.ssh/id_ed25519

Uses a challenge-response flow to authenticate via a pre-enrolled SSH key.

Grant-Secured Execution: apes run

Every command the agent wants to run goes through a grant:

apes run -- docker build -t myimage .

1. Apes loads the docker shapes adapter
2. Resolves the command into a structured authorization request
3. Creates a grant with the IdP
4. Waits for human approval
5. Fetches the signed grant JWT
6. Executes the command

Existing timed or always grants are reused automatically — no repeated approval for matching commands.

Privilege Escalation

apes run --as root -- apt-get upgrade

This routes through the escapes binary (separate Rust binary) which validates the grant JWT and executes the command with elevated privileges.

ape-shell: Grant-Secured Shell Wrapper

ape-shell is a drop-in replacement for bash -c that routes every command through apes run. Use it to sandbox AI coding agents (OpenClaw, Claude Code, etc.) so they can only execute pre-approved commands.

How It Works

AI Agent runs: $SHELL -c "git status"
                 ↓
       $SHELL = /usr/local/bin/ape-shell
                 ↓
       ape-shell -c "git status"
                 ↓
       apes run --shell -- bash -c "git status"
                 ↓
       1. Find existing ape-shell session grant?
          ✓ Yes → execute immediately
          ✗ No  → request grant → wait for approval → execute

Setup for an AI Agent Session

Most agent runtimes resolve the shell via the SHELL environment variable:

# Start your agent with SHELL pointing at ape-shell
SHELL=$(which ape-shell) openclaw
# or
SHELL=$(which ape-shell) claude

The first command the agent runs triggers a session grant request. The human approves it once (e.g. grant_type: timed, duration: 8h) and all subsequent commands reuse the same grant without interaction.

Example Session

# Human: login once
$ apes login

# Start the agent with ape-shell
$ SHELL=$(which ape-shell) openclaw

# Agent runs first command
> run: git status
ℹ Requesting ape-shell session grant on my-host
ℹ Grant requested: grant_abc123
ℹ Waiting for approval...

# Human approves in browser → command executes
On branch main

# Agent runs more commands — no more approvals needed
> run: git log --oneline -5
abc123 Latest commit
def456 Previous commit

Revoking Access

At any time, revoke the session grant to immediately stop the agent from executing any further commands:

apes grants list --audience ape-shell
apes grants revoke <grant-id>

MCP Server Mode

Expose all apes commands as Model Context Protocol tools so AI clients (Claude Desktop, Cursor, etc.) can request and use grants directly:

apes mcp --transport stdio
# or via HTTP/SSE
apes mcp --transport sse --port 3001

Configuration

Stored in ~/.config/apes/:

apes config get defaults.idp
apes config set defaults.idp https://id.example.com

Command Reference

Authentication

Grants

Execution

See Also

• Quickstart: Agent — set up an agent identity
• DDISA Protocol — underlying protocol spec
• apes mcp — exposes grant ops as MCP tools for AI clients