{
  "title": "Sign-in and setup",
  "description": "MachineMail CLI commands to sign in and out, show and check the credential in use with whoami and doctor, and register or claim an agent without a human.",
  "canonical": "https://machinemail.dev/docs/cli/commands/setup",
  "content": {
    "introduction": "Commands that sign the CLI in and out, show and check the credential in use, and register an agent without a human.",
    "commands": [
      {
        "command": "login",
        "summary": "Sign in with the browser (or an API key) and save the key to a profile",
        "exampleCommand": "machinemail login [flags]",
        "flags": [
          {"field": "--browser", "type": "boolean", "description": "Offer to open the browser for sign-in (default; --no-browser only prints the URL)."},
          {"field": "--paste", "type": "boolean", "description": "Paste an existing API key into a hidden prompt instead of signing in with the browser."},
          {"field": "--key <key|->", "type": "string", "description": "The API key, or - to read it from stdin (keeps it out of shell history)."},
          {"field": "--with-key", "type": "boolean", "description": "Read the key from stdin (same as --key -)."},
          {"field": "--no-verify", "type": "boolean", "description": "Save the key without checking it against the API (offline setup)."}
        ],
        "examples": [
          "machinemail login",
          "machinemail login --no-browser",
          "printf %s \"$MACHINEMAIL_API_KEY\" | machinemail login --key -",
          "machinemail login --profile work",
          "printf %s \"$WORK_API_KEY\" | machinemail login --profile work --key -"
        ]
      },
      {
        "command": "whoami",
        "summary": "Show the key, profile and API in use, and check the key.",
        "exampleCommand": "machinemail whoami",
        "examples": [
          "machinemail whoami",
          "machinemail whoami --profile work",
          "machinemail whoami --json | jq -r '.organization_id'"
        ]
      },
      {
        "command": "doctor",
        "summary": "Check the config, connectivity, key, clock and CLI version.",
        "exampleCommand": "machinemail doctor [flags]",
        "flags": [
          {"field": "--offline", "type": "boolean", "description": "Skip the checks that call the API."}
        ],
        "examples": [
          "machinemail doctor",
          "machinemail doctor --profile work --verbose",
          "machinemail doctor --json | jq '.checks[] | select(.status != \"ok\")'"
        ]
      },
      {
        "command": "register",
        "summary": "Register this agent (auth.md): a sandbox inbox and credentials, no human needed.",
        "exampleCommand": "machinemail register [flags]",
        "flags": [
          {"field": "--name <value>", "type": "string", "description": "Agent name shown to the human at claim time."},
          {"field": "--email <value>", "type": "string", "description": "Only this person can claim the agent."},
          {"field": "--claim", "type": "boolean", "description": "Start a claim now (default; --no-claim to skip and run machinemail claim later)."},
          {"field": "--wait", "type": "boolean", "description": "Wait until a human claims the agent."},
          {"field": "--force", "type": "boolean", "description": "Replace a profile that holds an API key."}
        ],
        "examples": [
          "machinemail register --name \"Research agent\"",
          "machinemail register --email ada@acme.dev --wait",
          "machinemail register --json | jq -r .inbox_id"
        ]
      },
      {
        "command": "claim",
        "summary": "Get a new claim code for a registered agent, and wait for a human to claim it.",
        "exampleCommand": "machinemail claim [flags]",
        "flags": [
          {"field": "--email <value>", "type": "string", "description": "Only this person can claim the agent."},
          {"field": "--wait", "type": "boolean", "description": "Wait until a human claims the agent."}
        ],
        "examples": [
          "machinemail claim",
          "machinemail claim --email ada@acme.dev --wait"
        ]
      },
      {
        "command": "logout",
        "summary": "Remove the stored key from a profile, and optionally revoke it.",
        "exampleCommand": "machinemail logout [flags]",
        "flags": [
          {"field": "--revoke", "type": "boolean", "description": "Revoke the key on the server too (--no-revoke: only remove it here). Asks on a terminal."}
        ],
        "examples": [
          "machinemail logout",
          "machinemail logout --yes",
          "machinemail logout --no-revoke --profile work"
        ]
      }
    ]
  }
}