otper-cli

Command-line interface for Otper — manage boards, lists, cards, labels, and comments from your terminal. Talks directly to the Otper GraphQL API and is also embeddable as a Node library.

npm install -g @ssntpl/otper-cli
otper auth:login
otper board:search "engineering"
otper card:list --list 42

Contents

• Install
• Authentication
• Configuration
• Command reference
• Output formats
• Library usage
• Examples
• Contributing
• License

Install

Requires Node.js 18+.

npm install -g @ssntpl/otper-cli

To use it programmatically in another Node project (no global install needed):

npm install @ssntpl/otper-cli

Authentication

Otper uses Bearer tokens. Generate a personal access token at https://otper.com/settings/tokens, then:

otper auth:login
# Otper API token: ********************
# ✓ Authenticated as Sambhav Aggarwal (@sam)
#   saved to /Users/you/.otper-cli/default/config.json

You can also pass the token directly:

otper auth:login --token "238|abc..." --base-url https://otper.com --team ssntpl

Or skip the saved config and use environment variables (handy for CI):

export OTPER_TOKEN="238|abc..."
export OTPER_BASE_URL="https://otper.com"
otper board:search engineering

To sign out:

otper auth:logout

Multiple profiles

Set OTPER_PROFILE to maintain isolated config files per environment:

OTPER_PROFILE=staging otper auth:login --base-url https://staging.otper.com
OTPER_PROFILE=staging otper board:list

Configuration

Credentials are stored at ~/.otper-cli/<profile>/config.json with mode 0600. The file looks like:

{
  "baseUrl": "https://otper.com",
  "token": "238|...",
  "team": "ssntpl"
}

Resolution order (highest priority first):

1. Command-line flags: --token, --base-url
2. Environment variables: OTPER_TOKEN, OTPER_BASE_URL, OTPER_TEAM
3. Saved config file

Command reference

Run otper <topic> --help to see commands within a topic, and otper <topic>:<command> --help for full flag documentation.

Auth

Board

List

Card

The --search flag on card:list and list:show accepts the same syntax as the Otper UI:

otper card:list --list 42 --search "labels:bug;assignee:alice;status:not completed"
otper card:list --list 42 --search "due date:overdue"
otper card:list --list 42 --search "#ENG123"

Label

Comment

Team

Misc

Output formats

Every command supports --format:

otper card:list --list 42 --format json | jq '.data[].title'
otper board:search team --format csv > boards.csv
otper card:move 1234 --to-list 50 --format silent && echo moved

Library usage

@ssntpl/otper-cli doubles as a typed library. Useful for openclaw plugins and other Node integrations:

import { OtperClient, boards, cards, lists } from '@ssntpl/otper-cli';

const client = new OtperClient({
  baseUrl: 'https://otper.com',
  token: process.env.OTPER_TOKEN!,
});

const board = await boards.getBoard(client, '7');
const inProgress = await lists.getListWithCards(client, '42', 1);

for (const card of inProgress!.cards.data) {
  console.log(card.card_number, card.title);
}

await cards.moveCard(client, '1234', '50'); // → Done

You can also load the user's saved config:

import { OtperClient, resolveConfig } from '@ssntpl/otper-cli';

const cfg = resolveConfig();             // throws if not authenticated
const client = OtperClient.fromConfig(cfg);

For raw GraphQL escape-hatches:

const data = await client.gql<{ me: { id: string } }>(
  `query { me { id name } }`,
);

Examples

Daily standup digest — list everything in progress and pipe into a summary:

otper card:list --list 42 --format csv > inprogress.csv

Move a card to Done in a script:

otper card:move "$CARD_ID" --to-list 120 --format silent

React to every unread comment (using jq):

otper card:comments "$CARD_ID" --format json \
  | jq -r '.[] | select(.reactions == []) | .id' \
  | xargs -I {} otper comment:react {} --reaction like --format silent

Use a different token per command (no config required):

OTPER_TOKEN="$BOT_TOKEN" otper card:comment 1234 --text "Build queued"

Contributing

git clone git@github.com:ssntpl/otper-cli.git
cd otper-cli
npm install
npm run dev -- board:search hello   # run from source via tsx
npm run build                       # compile to dist/
node bin/run.js --help              # run the compiled CLI

PRs welcome. Please:

• Add or update the README's command reference for any new commands.
• Keep GraphQL queries colocated in src/api/<resource>.ts.
• Mirror the existing BaseCommand/Column/output() pattern when adding commands so --format works uniformly.

License

MIT © SSNTPL