@oppira/cli 0.1.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +60 -110
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,147 +1,97 @@
1
- # Oppira CLI (`oppira`)
1
+ # Oppira CLI
2
2
 
3
- Terminal control for Oppira — competitor intelligence, playbook, studio, and ops —
4
- in one command. Dependency-free Node ESM (Node ≥ 20): runs with just `node`.
3
+ Drive **Oppira** from your terminal — competitor intelligence, your marketing
4
+ playbook, battlecards, the content studio, and the Oppira AI agent — with
5
+ scriptable, JSON-friendly output.
5
6
 
6
- ## Two execution modes
7
+ ## Requirements
7
8
 
8
- | Mode | How | Serves | Auth |
9
- |------|-----|--------|------|
10
- | **Remote** (default) | HTTP client against the deployed API | customers, agents, CI | JWT login, or durable `ca_` API key |
11
- | **Local / ops** | Imports the backend engines + Mongo directly | the team | backend `.env` (MONGO_URI + secrets) |
12
-
13
- Local mode reaches the **cron-only generators** (insights / alerts / battlecard) and
14
- the **intelligent scraper** without needing new HTTP endpoints — it mirrors the
15
- existing one-off scripts in `../scripts` (dotenv + `mongoose.connect` + engine call).
16
- It only works from a repo checkout with the backend secrets present.
9
+ - **Node.js 20+**
17
10
 
18
11
  ## Install
19
12
 
20
- **For end users (published package):**
21
-
22
13
  ```bash
23
14
  npm install -g @oppira/cli
24
15
  oppira --help
25
16
  ```
26
17
 
27
- **From the repo (team / ops mode):**
28
-
29
- ```bash
30
- cd cli && npm link # then `oppira` is on your PATH
31
- # or run directly:
32
- node cli/bin/oppira.js --help
33
- ```
34
-
35
- Only the repo checkout can run the local/ops commands (they need the backend
36
- `.env` + `node_modules`). The published package runs the **remote** commands.
37
-
38
- ## First run
18
+ ## Quick start
39
19
 
40
20
  ```bash
41
- oppira config set-url https://api.oppira.com # or leave default http://localhost:3008
42
- oppira auth login --email you@co.com # stores a JWT session (~/.oppira)
43
- oppira comp list
21
+ oppira config set-url https://api.oppira.com # your Oppira API endpoint
22
+ oppira auth login --email you@company.com # log in
23
+ oppira comp list # see your tracked competitors
24
+ oppira ask "how did my top competitor shift this month?"
44
25
  ```
45
26
 
46
- ## Authentication: session vs. API key
27
+ Config is stored in `~/.oppira/` (credentials are kept in a separate, locked-down
28
+ file). You can run against several accounts/environments with **profiles**
29
+ (`oppira config use <name>` or `--profile <name>`).
47
30
 
48
- Two ways to authenticate — pick one per profile:
31
+ ## Authentication
49
32
 
50
- 1. **Login session (works everywhere, default):**
51
- ```bash
52
- oppira auth login --email you@co.com
53
- ```
54
- Stores a JWT + refresh token; auto-refreshes. Best for interactive use.
33
+ Pick either method per profile:
55
34
 
56
- 2. **API key (durable — best for CI / agents / automation):**
57
- Generate the key in the **Oppira web app**, then paste it into the CLI:
58
- ```bash
59
- oppira auth key set ca_xxxxxxxx # or: oppira auth key generate
60
- ```
61
- > A `ca_` key unlocks the read-only `/mcp` analytics out of the box. To use it
62
- > for the **full REST command set**, the server must have
63
- > `OPPIRA_CLI_APIKEY_REST=true`. Until that's enabled, use `oppira auth login`
64
- > for REST commands.
35
+ - **Login (interactive):**
36
+ ```bash
37
+ oppira auth login --email you@company.com
38
+ ```
39
+ - **API key (best for scripts / CI):** create a key in the Oppira web app, then:
40
+ ```bash
41
+ oppira auth key set ca_xxxxxxxx
42
+ ```
65
43
 
66
- Config lives in `~/.oppira/config.json`; credentials (tokens, key) in
67
- `~/.oppira/credentials.json` (chmod 600). Multiple profiles are supported
68
- (`oppira config use <name>`, `--profile <name>`, or `OPPIRA_PROFILE`).
44
+ `oppira auth whoami` shows the current account; `oppira auth logout` clears it.
69
45
 
70
46
  ## Commands
71
47
 
72
- ```
73
- auth login | logout | whoami | key generate|revoke
74
- config show | list | set-url | set-output | use
75
- comp list | show | add | track | toggle-tracking | insights | alerts | rm
76
- discover profiles | job | suggestions | dismiss
77
- scrape run (intelligent, local) | raw <platform> --url
78
- insights list | summary | generate* (*local/ops force-run)
79
- alerts list | run*
80
- battlecard show | history | regen*
81
- playbook show | bootstrap | refresh-section | refresh-cluster
82
- studio posts | publish | calendars | calendar-generate | comments | draft-reply
83
- artifact get | export
84
- ask "<question>" (streams the unified agent reply)
85
- admin stats | ai-usage | errors | users* | set-plan*
86
- ```
48
+ | Group | What you can do |
49
+ |-------|-----------------|
50
+ | `oppira ask "…"` | Ask the Oppira AI agent (streams the answer). Reads args or stdin. |
51
+ | `oppira comp` | `list`, `show`, `add`, `track`, `toggle-tracking`, `insights`, `alerts`, `rm` |
52
+ | `oppira insights` | `list`, `summary`, `generate` |
53
+ | `oppira alerts` | `list`, `run` |
54
+ | `oppira battlecard` | `show`, `history`, `regen` |
55
+ | `oppira playbook` | `show`, `bootstrap`, `refresh-section`, `refresh-cluster` |
56
+ | `oppira discover` | `profiles`, `suggestions`, `dismiss` |
57
+ | `oppira studio` | posts, calendars, comments, templates, image generation, publishing *(Pro)* |
58
+ | `oppira artifact` | `get`, `export` (reports / decks / diagrams) |
59
+ | `oppira config` / `oppira auth` | profiles, API URL, login, API keys |
60
+
61
+ Run `oppira <group> --help` for a group's commands, or `oppira <group> <command> --help` for details.
87
62
 
88
- Global flags: `--json` (machine output for scripts/agents), `--local`,
89
- `--profile <name>`, `--help`, `--version`. Every command exits non-zero on failure.
63
+ Feature access follows your Oppira plan (e.g. the AI agent, playbook and
64
+ battlecards are available from **Basic** up; **Studio** is **Pro**). If a command
65
+ isn't available on your plan you'll get a clear upgrade message.
90
66
 
91
- ### Examples
67
+ ## Examples
92
68
 
93
69
  ```bash
94
- oppira ask "compare Acme and Globex activity this month"
70
+ # Ask the agent, pipe the answer into your own tooling
95
71
  oppira ask "summarize my playbook" --json | jq -r .text
96
- oppira scrape run Acme --platforms fb,ig # ops, local mode
97
- oppira insights generate --email client@co.com # force cron-only generator
98
- oppira battlecard regen Globex
99
- oppira admin errors --limit 20
100
- oppira admin ai-usage --by-plan
101
- ```
102
72
 
103
- ## Server-side: enable API-key REST access (opt-in)
73
+ # Competitors
74
+ oppira comp show Acme
75
+ oppira comp add "Globex" --website globex.com --instagram https://instagram.com/globex
104
76
 
105
- Granting a `ca_` key full REST authority (so users/CI can drive the CLI with just
106
- an API key instead of a 15-min JWT) is a deliberate security decision and is **off
107
- by default**. To turn on the "generate a key in the web app → use the CLI" flow,
108
- set on the server:
77
+ # Refresh strategic docs on demand
78
+ oppira insights generate
79
+ oppira battlecard regen Acme
109
80
 
110
- ```
111
- OPPIRA_CLI_APIKEY_REST=true
81
+ # Export a generated report
82
+ oppira artifact export <id> --format pdf
112
83
  ```
113
84
 
114
- Until then, REST commands authenticate with the JWT session from `oppira auth login`.
85
+ ## Scripting & automation
115
86
 
116
- ## Publishing (maintainers)
117
-
118
- The package is publish-ready (`publishConfig.access = public`, `files` whitelist).
87
+ - Add `--json` to any command for machine-readable output.
88
+ - Commands exit non-zero on failure, so they behave well in CI.
89
+ - `oppira ask` reads a question from arguments **or** piped stdin.
119
90
 
120
91
  ```bash
121
- cd cli
122
- npm version patch # or minor/major — bump the version
123
- npm publish # publishes @oppira/cli to npm
92
+ echo "what should I post about this week?" | oppira ask --json
124
93
  ```
125
94
 
126
- Prerequisites & notes:
127
- - You must own/belong to the **`@oppira`** npm org for the scoped name. If you don't,
128
- rename `name` in package.json to an unscoped `oppira-cli` (the `oppira` command name
129
- is unchanged) and drop `publishConfig`.
130
- - `npm login` first; the publish is public.
131
- - Only `bin/`, `src/`, `README.md` ship (the `files` field) — no repo internals.
132
- - End users then: `npm install -g @oppira/cli`.
133
-
134
- ## Status (phased build)
135
-
136
- - **Working now:** auth/config, competitors (+ analytics: timeline/compare/top-posts/tone in
137
- local mode), discover, playbook, insights/alerts/battlecard reads, `ask` (SSE), artifact
138
- get/export, admin (reads + user mgmt + `script` runner folding `../scripts`), studio
139
- (posts/calendars/comments/templates/formats/settings/channels/assets/policy + actions),
140
- local/ops force-generators + intelligent scrape.
141
- - **Remote force-generate:** `insights generate`, `alerts run`, `battlecard regen` now hit
142
- owner-scoped REST endpoints by default (added to the backend); pass `--local` to run the
143
- engine directly instead.
144
- - **Follow-up (still open):** MCP-backed analytics over HTTP (so timeline/compare/top-N work
145
- remotely, not just local), deeper Studio (image-layer editing, ads), and per-endpoint
146
- rate-limiting on the force-generate routes.
147
- ```
95
+ ## Support
96
+
97
+ Questions or issues? Reach the Oppira team at [oppira.com](https://oppira.com).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@oppira/cli",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "description": "Oppira CLI — terminal control for the adaptive marketing system (competitor intelligence, playbook, studio, ops).",
5
5
  "type": "module",
6
6
  "bin": {