# Signal CLI

Signal resources through the cmdhub CLI.

## Install

```bash
cmdhub get signal
```

## Authentication

Device link

## Agent-Readable Catalog

- Machine-readable command catalog: `/cli/signal/catalog.json`
- Stable command anchors use the `cmd-...` IDs listed under each command.
- Inspect this catalog before planning tool use for command paths, examples, flags, mutation markers, and dry-run support.

## Overview

```bash
# Inspect auth state and available command schemas
signal auth status --json
signal schema
```

## CLI Overview

Focused Signal linked-device CLI for login, auth recovery, contacts, groups, local messages, sends, local message cleanup, and device inspection.

## Generated Coverage

- Command groups: `16`
- Total documented command nodes: `30`
- Live examples: `7`
- Lifecycle surfaces: `auth`, `doctor`, `capabilities`, `schema`, `resolve`, `version`
- Machine-readable output: `--json`, `--jsonl`
- Human views: `summary`, `full`

## Auth Contract

- Auth mode: Device link
- Standard commands: `auth login`, `auth status`, `auth whoami`, `auth logout`
- `auth status --json` reports `tool`, `profile`, `provider`, `authenticated`, and `suggested_next_step`.
- `auth whoami --json` is the stable way to answer identity questions.

## Agent Safety Notes

- Discovery commands such as `list`, `search`, `get`, `resolve`, `schema`, `doctor`, `capabilities`, `status`, and `whoami` are the safest commands to run first.
- Treat commands marked as mutating as state-changing local or provider operations.
- Mutating command paths: `signal login`, `signal auth login`, `signal auth logout`, `signal logout`, `signal profile create`, `signal profile delete`, `signal message send`, `signal message delete`
- Commands with `--dry-run`: `signal message delete`

## Global Flags

- `--json` (bool): Emit one JSON payload where supported
- `--jsonl` (bool): Emit newline-delimited JSON where supported
- `--output` (string): Output mode: human|json
- `--quiet` (bool): Suppress human next-step guidance
- `--store` (path): Path to the local Signal state database
- `--view` (string): Human view: summary|full

## Command Reference

### `signal login`

- Anchor: `cmd-signal-login`
- Mutates state: `yes`
- Supports dry run: `no`

Link this CLI as a Signal secondary device

Example:

```bash
signal login
signal login --device-name laptop
```

Flags:

- `--device-name` (string): Device name shown in Signal mobile
- `--timeout` (duration): How long to wait for phone approval
- `--show-url` (bool): Print the raw provisioning URL
- `--servers` (string): Signal server set: production|staging

### `signal auth`

- Anchor: `cmd-signal-auth`
- Mutates state: `no`
- Supports dry run: `no`

auth commands

#### `signal auth login`

- Anchor: `cmd-signal-auth-login`
- Mutates state: `yes`
- Supports dry run: `no`

Link this CLI as a Signal secondary device

Example:

```bash
signal auth login
```

Flags:

- `--device-name` (string): Device name shown in Signal mobile
- `--timeout` (duration): How long to wait for phone approval
- `--show-url` (bool): Print the raw provisioning URL
- `--servers` (string): Signal server set: production|staging

#### `signal auth status`

- Anchor: `cmd-signal-auth-status`
- Mutates state: `no`
- Supports dry run: `no`

Show the linked Signal identity

Example:

```bash
signal auth status
```

#### `signal auth whoami`

- Anchor: `cmd-signal-auth-whoami`
- Mutates state: `no`
- Supports dry run: `no`

Show the linked Signal identity

Example:

```bash
signal auth whoami
```

#### `signal auth logout`

- Anchor: `cmd-signal-auth-logout`
- Mutates state: `yes`
- Supports dry run: `no`

Remove the local linked-device database

Example:

```bash
signal auth logout --yes
```

Flags:

- `--yes` (bool): Delete local state without confirmation

### `signal status`

- Anchor: `cmd-signal-status`
- Mutates state: `no`
- Supports dry run: `no`

Show the linked Signal identity

Example:

```bash
signal status
```

### `signal whoami`

- Anchor: `cmd-signal-whoami`
- Mutates state: `no`
- Supports dry run: `no`

Show the linked Signal identity

Example:

```bash
signal whoami
```

### `signal logout`

- Anchor: `cmd-signal-logout`
- Mutates state: `yes`
- Supports dry run: `no`

Remove the local linked-device database

Example:

```bash
signal logout --yes
```

Flags:

- `--yes` (bool): Delete local state without confirmation

### `signal profile`

- Anchor: `cmd-signal-profile`
- Mutates state: `no`
- Supports dry run: `no`

profile commands

#### `signal profile list`

- Anchor: `cmd-signal-profile-list`
- Mutates state: `no`
- Supports dry run: `no`

Explain the fixed linked-device profile

Example:

```bash
signal profile list
```

#### `signal profile create`

- Anchor: `cmd-signal-profile-create`
- Mutates state: `yes`
- Supports dry run: `no`

Report that Signal profile creation is unsupported

Example:

```bash
signal profile create --name cmdhub-eval-temp
```

Flags:

- `--name` (string): Requested profile name

#### `signal profile delete`

- Anchor: `cmd-signal-profile-delete`
- Mutates state: `yes`
- Supports dry run: `no`

Report that Signal profile deletion is unsupported

Example:

```bash
signal profile delete cmdhub-eval-temp
```

Flags:

- `--yes` (bool): Acknowledge the cleanup check

### `signal sync`

- Anchor: `cmd-signal-sync`
- Mutates state: `no`
- Supports dry run: `no`

Receive and store pending messages

Example:

```bash
signal sync --once
```

Flags:

- `--once` (bool): Exit once the current server queue is empty

### `signal contact`

- Anchor: `cmd-signal-contact`
- Mutates state: `no`
- Supports dry run: `no`

contact commands

#### `signal contact list`

- Anchor: `cmd-signal-contact-list`
- Mutates state: `no`
- Supports dry run: `no`

List synced contacts

Example:

```bash
signal contact list
```

### `signal group`

- Anchor: `cmd-signal-group`
- Mutates state: `no`
- Supports dry run: `no`

group commands

#### `signal group list`

- Anchor: `cmd-signal-group-list`
- Mutates state: `no`
- Supports dry run: `no`

List synced groups

Example:

```bash
signal group list
signal group list --verbose
```

Flags:

- `--verbose` (bool): Show more group metadata

### `signal message`

- Anchor: `cmd-signal-message`
- Mutates state: `no`
- Supports dry run: `no`

message commands

#### `signal message list`

- Anchor: `cmd-signal-message-list`
- Mutates state: `no`
- Supports dry run: `no`

List local messages for a contact or group

Example:

```bash
signal message list --contact c1
signal message list --group g1
```

Flags:

- `--contact` (string): Contact ref, ACI UUID, or service ID
- `--group` (string): Group ref or group master key
- `--from` (int): Local message offset

#### `signal message get`

- Anchor: `cmd-signal-message-get`
- Mutates state: `no`
- Supports dry run: `no`

Hidden alias for exact message lookup

Example:

```bash
signal message get m1
signal resolve m1
```

#### `signal message send`

- Anchor: `cmd-signal-message-send`
- Mutates state: `yes`
- Supports dry run: `no`

Send a message to a contact or group

Example:

```bash
signal message send --to c1 --message hello
signal message send --group g1 --message hello
```

Flags:

- `--to` (string): Recipient contact ref or ACI UUID
- `--group` (string): Group ref or group master key
- `--message` (string): Message body
- `--attach` (path): Attachment path; repeatable

#### `signal message delete`

- Anchor: `cmd-signal-message-delete`
- Mutates state: `yes`
- Supports dry run: `yes`

Delete one local synced message by ref

Example:

```bash
signal message delete m1 --yes
```

Flags:

- `--yes` (bool): Confirm local deletion for non-disposable messages
- `--dry-run` (bool): Preview local deletion without changing the store

### `signal device`

- Anchor: `cmd-signal-device`
- Mutates state: `no`
- Supports dry run: `no`

device commands

#### `signal device list`

- Anchor: `cmd-signal-device-list`
- Mutates state: `no`
- Supports dry run: `no`

List linked devices

Example:

```bash
signal device list
```

### `signal doctor`

- Anchor: `cmd-signal-doctor`
- Mutates state: `no`
- Supports dry run: `no`

Run local Signal CLI diagnostics

Example:

```bash
signal doctor
signal doctor --json
```

### `signal capabilities`

- Anchor: `cmd-signal-capabilities`
- Mutates state: `no`
- Supports dry run: `no`

Describe command capabilities for automation and audits

Example:

```bash
signal capabilities --json
```

### `signal schema`

- Anchor: `cmd-signal-schema`
- Mutates state: `no`
- Supports dry run: `no`

Print command input and output schemas

Example:

```bash
signal schema --json
signal schema auth.status --out --json
```

Flags:

- `--input` (bool): Show input schema for one command
- `--out` (bool): Show output schema for one command

### `signal resolve`

- Anchor: `cmd-signal-resolve`
- Mutates state: `no`
- Supports dry run: `no`

Resolve a local ref to its canonical provider value

Example:

```bash
signal resolve c1
signal resolve aci1
signal resolve me1 --json
```

### `signal version`

- Anchor: `cmd-signal-version`
- Mutates state: `no`
- Supports dry run: `no`

Print build and license information

Example:

```bash
signal version
```

## Live Examples

### Auth

#### Inspect linked-device status

Reports the recovery path when the CLI has not been linked yet.

_Example metadata: provider state: unlinked._

```bash
signal status
```

```text
Signal auth status
Linked: no
Profile: default
Credential type: linked-device QR store
Store: {store}
Status: not linked yet

Next steps:
- Link this CLI: signal login
- Inspect auth state: signal auth status
- Run diagnostics: signal doctor
```

### Messages

#### Send with a ref

Shows the canonical send command accepting contact and group refs.

_Example metadata: provider state: unlinked._

```bash
signal message send --help
```

```text
Send a message to a contact or group

Usage: signal message send [OPTIONS] --message <MESSAGE>

Options:
      --json                  Emit one JSON payload where supported
      --to <TO>               Recipient contact ref or ACI UUID
      --group <GROUP>         Group ref or group master key hex
      --jsonl                 Emit newline-delimited JSON where supported
  -m, --message <MESSAGE>     
      --view <VIEW>           [default: summary] [possible values: summary, full]
      --attach <ATTACHMENTS>  Path to an attachment; repeat for more than one
      --quiet                 Suppress human next-step guidance
      --limit <LIMIT>         Limit list output where supported; 0 means no cap
      --store <STORE_PATH>    Path to the local Signal state database
  -h, --help                  Print help
  -V, --version               Print version
```

### Diagnostics

#### Check local Signal readiness

Shows local store status and the next login step without requiring a linked account.

_Example metadata: provider state: unlinked._

```bash
signal doctor
```

```text
signal doctor
status: needs_login
store: {store}
checks:
- credential_backend: ok - local SQLite linked-device store
- auth: missing - not linked yet; expected store at {store}
- connectivity: skipped - link this CLI before checking Signal service connectivity

Next steps:
- Link this CLI: signal login
- Inspect auth state: signal auth status
- Run diagnostics: signal doctor
```

#### Print version

Prints the Signal CLI version.

_Example metadata: provider state: unlinked._

```bash
signal version
```

```text
signal 0.1.0
license: AGPL-3.0-only
engine: presage/libsignal-service

Next steps:
- Check linked-device status: signal auth status
- Inspect command contract: signal capabilities --json
- Run diagnostics: signal doctor
```

### Schemas

#### Inspect command capabilities

Summarizes supported commands and points agents to the structured contract.

_Example metadata: provider state: unlinked._

```bash
signal capabilities
```

```text
signal capabilities
Focused Signal linked-device CLI for login, auth recovery, contacts, groups, local messages, sends, local message cleanup, and device inspection.
auth: device_link (linked-device QR)
machine contract: signal capabilities --json
commands:
  signal login	auth	Run `signal login` to link this CLI as a secondary device.
  signal auth login	auth	Run `signal auth login` to link this CLI as a secondary device.
  signal status	read_only	Run `signal login` first if no linked device is configured.
  signal whoami	read_only	Run `signal login` first if no linked device is configured.
  signal auth status	read_only	Run `signal login` first if no linked device is configured.
  signal auth whoami	read_only	Run `signal login` first if no linked device is configured.
  signal logout	destructive	Run `signal logout --yes` only when you want to remove local linked-device state.
  signal auth logout	destructive	Run `signal auth logout --yes` only when you want to remove local linked-device state.
  signal profile list	read_only	Signal has one fixed linked-device profile; use `signal auth status` for identity.
  signal profile create	unsupported_noop	Run `signal profile create --name cmdhub-eval-temp` to get a no-change auth redirect.
  signal profile delete	unsupported_noop	Run `signal profile delete cmdhub-eval-temp` to verify no local profile cleanup is needed.
  signal sync	read_only	Run `signal sync --once` to receive and store pending messages.
  signal contact list	read_only	Run `signal contact list` after `signal sync --once` to list synced contacts.
  signal group list	read_only	Run `signal group list --verbose` for more local group metadata.
  signal message list	read_only	Run `signal message list --contact c1` or `signal message list --group g1`.
  signal message get	read_only	Alias: `signal message get m1` runs `signal resolve m1`.
  signal message send	mutating	Run `signal message send --to c1 --message <text>` or `signal message send --group g1 --message <text>`.
  signal message delete	destructive	Run `signal message delete m1 --yes` for confirmed local-only cleanup; disposable cmdhub-eval messages can be deleted without --yes.
  signal device list	read_only	Run `signal device list` to list linked devices for the account.
  signal doctor	read_only	Run `signal doctor` to check local store and linked-device readiness.
  signal capabilities	read_only	Run `signal capabilities --json` for the structured command contract.
  signal schema	read_only	Run `signal schema --json` for all command schemas.
  signal resolve	read_only	Run `signal resolve c1` after `signal contact list` or `signal resolve aci1` after `signal auth status`.
  signal version	read_only	Run `signal version` to show build and license information.
Run `signal capabilities --json` for the structured command contract.

Next steps:
- Check linked-device status: signal auth status
- Inspect schemas: signal schema --json
- Run diagnostics: signal doctor
```

#### Inspect auth status schema

Prints the machine-readable output schema for auth status.

_Example metadata: provider state: unlinked._

```bash
signal schema auth.status --out --json
```

```text
{
  "tool": "signal",
  "version": "0.1.0",
  "schemas": [
    {
      "schema_id": "signal.auth.status.output.v1",
      "version": "1",
      "tool": "signal",
      "resource": "auth",
      "action": "status",
      "direction": "output",
      "json_schema": {
        "additionalProperties": false,
        "properties": {
          "command": {
            "description": "Signal command field",
            "type": [
              "string",
              "boolean",
              "integer",
              "array",
              "object",
              "null"
            ]
          },
          "items": {
            "description": "Signal items field",
            "type": [
              "string",
              "boolean",
              "integer",
              "array",
              "object",
              "null"
            ]
          },
          "next_steps": {
            "description": "Signal next_steps field",
            "type": [
              "string",
              "boolean",
              "integer",
              "array",
              "object",
              "null"
            ]
          },
          "result": {
            "description": "Signal result field",
            "type": [
              "string",
              "boolean",
              "integer",
              "array",
              "object",
              "null"
            ]
          },
          "tool": {
            "description": "Signal tool field",
            "type": [
              "string",
              "boolean",
              "integer",
              "array",
              "object",
              "null"
            ]
          }
        },
        "required": [
          "tool",
          "command"
        ],
        "type": "object"
      },
      "required": [
        "tool",
        "command"
      ],
      "optional": [
        "items",
        "result",
        "next_steps"
      ],
      "examples": [
        "signal auth status",
        "signal auth status --json"
      ]
    }
  ],
  "next_steps": [
    {
      "label": "Inspect auth status schema",
      "command": "signal schema auth.status --out --json",
      "safety": "read_only"
    },
    {
      "label": "Inspect command contract",
      "command": "signal capabilities --json",
      "safety": "read_only"
    }
  ]
}
```

### Contacts

#### Discover contact refs

Shows the canonical contact listing command that creates c1-style refs.

_Example metadata: provider state: unlinked._

```bash
signal contact list --help
```

```text
List synced contacts

Usage: signal contact list [OPTIONS]

Options:
      --json                Emit one JSON payload where supported
      --jsonl               Emit newline-delimited JSON where supported
      --view <VIEW>         [default: summary] [possible values: summary, full]
      --quiet               Suppress human next-step guidance
      --limit <LIMIT>       Limit list output where supported; 0 means no cap
      --store <STORE_PATH>  Path to the local Signal state database
  -h, --help                Print help
  -V, --version             Print version
```