Skip to content

docs: list routine run --json / --quiet, --config and clear-session in the mirror docs (#182) - #191

Merged
garretpremo merged 1 commit into
devfrom
issues/182-mirror-docs
Oct 19, 2026
Merged

garretpremo merged 1 commit into
devfrom
issues/182-mirror-docs

Conversation

@garretpremo

@garretpremo garretpremo commented Oct 19, 2026 •

Copy link
Copy Markdown
Contributor

Closes #182

Summary

The shipped mirror docs (AGENTS.md, GEMINI.md, and the write-routine and setup-api skills) now cover every new flag in this release: routine run --json and -s/--quiet (#177), config clear-session (#179), and the global --config <name> (#180). The wording is copied from CLAUDE.md. Per #182's triage, this is the last PR of the release, so the mirrors are updated in a single pass against CLAUDE.md's final text (dev 8b5e090, after #190).

The wiki goes live on push, so the wiki edits aren't in this PR. They're listed below under "Post-release wiki edits", to be applied as written once the release ships.

What changes

Routine Commands blocks: AGENTS.md, GEMINI.md, skills/write-routine/SKILL.md

Three lines are added, matching CLAUDE.md:

<cli> --config <env> routine run <name>   # Run against another configured environment
<cli> routine run <name> --json           # Emit RoutineResult as JSON to stdout
<cli> routine run <name> -s / --quiet     # Print only what the routine's commands print (failures still on stderr)

write-routine keeps its own column alignment.

Global --config <name>: AGENTS.md, GEMINI.md

CLAUDE.md "Sessions"

skills/setup-api/SKILL.md Troubleshooting

  • New bullet: Edited config.json by hand → run apijack config clear-session, or apijack config clear-session <env> for another environment.

Not changed

The broader AGENTS.md / GEMINI.md resync is out of scope per the triage: built-in resolvers, programmatic runRoutine, the plugin system, SessionAuthStrategy options, project extensions, aliases and opt-in auth.

Acceptance criteria

Test plan

  • bun test: 1324 pass / 0 fail (docs only, run once)
  • bun run lint: 0 errors
  • Mirror subsections diffed against CLAUDE.md on dev 8b5e090: identical.
  • Self-review: a reviewer subagent checked the mirror wording against CLAUDE.md and the wiki edits against the current wiki and the shipped code. Verdict: the staged diff was clean. Its eight findings are all fixed:
    • Mostly in this body's wiki section: a broken heading anchor, a missed Invalidating the Session line, the env-var case in the config clear-session text, exact text for the --config section, and keeping the legacy gitignore line.
    • Two wording nits in the docs: config field names in the CLAUDE.md bullet, and <env> in the setup-api bullet.
  • Review round 1 (changes requested, PR-body only):
    • The Recommended-Gitignore edit used a trailing # comment, which gitignore treats as part of the pattern. It now sits on its own line.
    • Added the stale "Priority" block and sentence after Global --config <name> option to run a command against any configured environment #180, the routine run intro, and a custom-configPath row in the session-location table.
    • The other wiki gitignore snippets (Project-Mode.md, Managing-Environments.md) only use .apijack/ with no trailing comments, so they're unaffected.

Post-release wiki edits

Apply these to normalled/apijack.wiki once the release containing #177, #179, #180 and #182 has shipped.

CLI-Command-Reference.md

  1. ## routine run, intro. "Steps are run in order; progress is printed to stdout." → "Steps are run in order; progress is printed to stdout (unless --json or -s/--quiet is passed)."

    Flags table. Add two rows after --dry-run:

    | `--json` | flag | Emit the `RoutineResult` as JSON to stdout (silences progress output) |
    | `-s, --quiet` | flag | Print only what the routine's commands print: no banner, step lines or summary. Failures still go to stderr |

    Below the table, add:

    `--quiet` and `--json` can't be combined. `--quiet --dry-run` prints only the resolved commands.

    Add to the Examples block:

    <cli> routine run create-pet --json
    <cli> routine run create-pet -s
    <cli> --config staging routine run create-pet
  2. ## config switch. After "All subsequent commands use the URL and credentials of the named environment.", add:

    Each environment keeps its own cached session, so switching away and back doesn't log you out. To run one command against another environment without switching, use the global [`--config <name>`](#global-option---config-name).
  3. New section ## config clear-session, after ## config switch:

    ## config clear-session
    
    **Syntax:** `<cli> config clear-session [name] [--all]`
    
    Delete a cached session so the next command logs in again. With no name it clears the session the next command would use: the environment selected with `--config`; otherwise the `<CLI>_URL` / `_USER` / `_PASS` credentials, if set; otherwise the active environment.
    
    **Arguments:**
    
    | Argument | Description |
    |----------|-------------|
    | `[name]` | Environment whose session to delete. An unknown name exits 1 with the list of configured environments |
    
    **Flags:**
    
    | Flag | Type | Description |
    |------|------|-------------|
    | `--all` | flag | Delete every environment's cached session. Can't be combined with a name |
    
    **Examples:**
    
    ```bash
    <cli> config clear-session
    <cli> config clear-session staging
    <cli> config clear-session --all
    ```
    
    ---
  4. New section before ## Global Flags (Generated API Commands):

    ## Global option: `--config <name>`
    
    **Syntax:** `<cli> --config <name> <command> [args...]`
    
    Run a single invocation against any environment in `config.json`, without changing the active one.
    
    ```bash
    <cli> --config staging pets list
    <cli> --config staging routine run create-pet --set pet_name=Luna   # every step and sub-routine uses staging
    ```
    
    - Uses that environment's URL, credentials, auth type, `sessionAuth` / `refreshOn` and its own session file. It wins over `<CLI>_URL` / `_USER` / `_PASS`.
    - It goes before the command; `--config=<name>` works too. A `--config` after the command belongs to that command (e.g. a generated flag for an API field named `config`); a command without one rejects it with a hint to move it.
    - An unknown name fails with the list of configured environments.
    - `<cli> --config <name> mcp` passes the environment on to every CLI call the MCP server makes.
    - Programmatic: `runRoutine(name, { config: '<name>' })`, or `createCli({ environment: '<name>', ... })` (a leading `--config` still wins).
    
    ---

Writing-Routines.md

"Running and validating routines" table. Add three rows after routine run <name> --dry-run:

| `routine run <name> --json` | Emit the `RoutineResult` as JSON to stdout |
| `routine run <name> -s` / `--quiet` | Print only what the routine's commands print; failures still go to stderr (can't be combined with `--json`) |
| `--config <env> routine run <name>` | Run against another configured environment without switching (`--config` goes before the command) |

Recommended-Gitignore.md

Sessions moved from .apijack/session.json to .apijack/sessions/<env>.json (#179). Keep ignoring the old file until it's deleted, because it may still hold valid tokens.

  • "Recommended patterns" block: replace the .apijack/session.json line with the three lines below. gitignore only treats # as a comment at the start of a line, so the comment has to sit on its own line:

    .apijack/sessions/
    # Written by releases before per-environment sessions; drop once the file is deleted
    .apijack/session.json
  • "Minimal gitignore" block: same replacement.

  • "What to commit" table: replace the .apijack/session.json row with these two rows:

    | `.apijack/sessions/` | **No** | One session file per environment (tokens/cookies). It also ignores itself via its own `.gitignore` |
    | `.apijack/session.json` | **No** | Written by releases before per-environment sessions; no longer read or written. Delete it |

Authentication-Configuration.md ("Environment Variable Naming" and "Session Caching")

  • "Environment Variable Naming", first sentence. "Environment variables take priority over the config file." → "Environment variables take priority over the config file's active environment, but not over a leading --config <name> (see CLI Command Reference)."

  • "Priority" block (Global --config <name> option to run a command against any configured environment #180):

    --config <name> / createCli({ environment })  →  environment variables  →  config file active environment  →  null (unauthenticated)
    
  • "Session File Location" table: ~/.<cliName>/session.json → ~/.<cliName>/sessions/<env>.json, and .apijack/session.json → .apijack/sessions/<env>.json. Add a third row:

    | Custom `configPath` (own `bin/<cli>.ts`) | `<directory of configPath>/sessions/<env>.json` |

    Add below the table:

    Each environment in `config.json` has its own file; the name is percent-encoded (`my env` → `my%20env.json`). Credentials from `<CLI>_URL` / `_USER` / `_PASS` use a separate file. The file records the environment, `baseUrl` and username it was minted for, and a session recorded for a different `baseUrl` or username is ignored. Saving an environment's credentials (`setup`, `config import`, `config update-password`) clears its session; after editing `config.json` by hand, run `config clear-session`.
  • "AuthSession Format". Add after the field table:

    On disk, the session is wrapped with the environment it belongs to: `{ "env": "staging", "baseUrl": "https://…", "username": "…", "session": { …AuthSession… } }`.
  • "Session Lifecycle", step 1: "Load session.json from disk." → "Load the environment's session file from disk (ignored if it was recorded for a different baseUrl or username)."

  • "Invalidating the Session": "This deletes session.json." → "This deletes the environment's session file (sessions/<env>.json). From the CLI, config clear-session [name] [--all] does the same."

Managing-Environments.md ("Switching environments")

After the existing paragraph, add:

Each environment keeps its own cached session, so switching back doesn't log you out. `config clear-session [name] [--all]` deletes a cached session when you need a fresh login.

To run a single command against another environment without switching, put `--config <name>` before the command:

```
$ apijack --config staging pets list
```

…n the mirror docs (#182)

AGENTS.md, GEMINI.md and the write-routine skill now list routine run
--json, -s/--quiet and the --config <env> routine run line in their
Routine Commands blocks, and AGENTS.md / GEMINI.md carry CLAUDE.md's
"Running one command against another environment" subsection. Wording
is copied from CLAUDE.md.

CLAUDE.md's Sessions section and the setup-api troubleshooting list now
say to run config clear-session after editing credentials in
config.json by hand, since hand edits bypass the clear-on-save.
@github-actions github-actions Bot added the needs review Open PR awaiting review label Oct 19, 2026
@garretpremo garretpremo added review in progress Review is actively underway and removed needs review Open PR awaiting review labels Oct 19, 2026

@garretpremo garretpremo left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 Automated review by claude — generated by the review-issue skill. Treat as advisory; a human still owns the merge decision.

The doc diff itself is correct. In AGENTS.md and GEMINI.md, the Routine Commands lines, the Built-in Commands table and the "Running one command against another environment" subsection match origin/dev:CLAUDE.md (8b5e090) byte for byte. write-routine and setup-api match the shipped routine run / config clear-session / leading --config code, and the new CLAUDE.md Sessions bullet matches SessionManager.load(): url and user are part of the binding check, password isn't. One thing blocks: the "Post-release wiki edits" section can't be applied as written. Applying it would stop git from ignoring the legacy session file.

Blocking:

  • Recommended-Gitignore.md: the replacement line has a trailing comment, and gitignore doesn't support those. # only starts a comment at the beginning of a line. So .apijack/session.json # written by releases before per-environment sessions; drop once the file is deleted becomes one literal pattern, and it no longer matches .apijack/session.json. I checked this in a scratch repo with exactly those two lines. git check-ignore -v .apijack/session.json matched nothing, and git status listed ?? .apijack/session.json. A project that follows the edit would start committing the legacy file, which the body itself says "may still hold valid tokens". Both the "Recommended patterns" block and the "Minimal gitignore" block ("same replacement") have this problem. Put the comment on its own line:

    .apijack/sessions/
    # Written by releases before per-environment sessions; drop once the file is deleted
    .apijack/session.json

    This only needs a PR-body edit. No commit is required.

Non-blocking observations
  • Authentication-Configuration.md → "Priority" (around line 77) is stale after #180, and the wiki list doesn't touch it. It still reads Environment variables → config file active environment → null. A leading --config <name> (and createCli({ environment })) now comes before the env vars (resolveEnvironment in src/config.ts skips them when opts.environment is set). Consider adding --config <name> → at the front, with a link to the new CLI-Command-Reference section.
  • CLI-Command-Reference.md → ## routine run intro. "progress is printed to stdout" is no longer true with --json or -s. A small rewording, such as "(unless --json or --quiet)", would keep it consistent with the new flag rows.
  • Authentication-Configuration.md → "Session File Location" table. Sessions now sit next to config.json, so a third row for a custom configPath (<dir of configPath>/sessions/<env>.json) would be accurate. CLAUDE.md already documents this case.
  • I verified the rest of the wiki list against the current wiki (a20bc7c) and the code on dev, and it applies as written:
    • Every target heading, table and sentence exists.
    • The #global-option---config-name anchor matches the new heading.
    • The config clear-session default order (--config → <CLI>_URL/_USER/_PASS → active) matches resolveEnvironment.
    • Unknown-name and name-with---all exit 1, matching configClearSessionAction.
    • The on-disk { env, baseUrl, username, session } shape matches SessionFile.
    • Every session.json reference in the wiki is covered.
Nitpicks
  • The new AGENTS.md/GEMINI.md subsection keeps CLAUDE.md's domain-specific example (admin matters delete 7, routine run cleanup --set matterId=2). That follows the "copy verbatim" triage decision, so it's fine here. The generic pets/resources examples used elsewhere (and in this PR's wiki text) might suit a future CLAUDE.md pass better.

@garretpremo garretpremo added changes requested Review found blocking issues and removed review in progress Review is actively underway labels Oct 19, 2026

@garretpremo garretpremo left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 Automated review by claude — generated by the review-issue skill. Treat as advisory; a human still owns the merge decision.

Follow-up on the updated PR body. The head is still fc1a50c; there are no new commits. The blocker is fixed, nothing new blocks, and this is ready for a first pass.

  • Blocker fixed. In both gitignore blocks, the Recommended-Gitignore.md comment now sits on its own line. I tested the "Recommended patterns" block in a scratch repo. git check-ignore -v matches .apijack/session.json (line 5), .apijack/sessions/dev.json (line 3) and .apijack/config.json, and git status shows only .gitignore as untracked.
  • Non-blocking items addressed. I checked each one against the current wiki (a20bc7c) and dev:
    • ## routine run intro. The intro sentence being replaced exists word for word.
    • "Environment Variable Naming" sentence. The sentence being replaced exists word for word, and the CLI-Command-Reference#global-option---config-name link matches the new heading.
    • "Priority" block. The new order matches resolveEnvironment(): a selected environment skips the env vars, and a leading --config overrides createCli({ environment }).
    • Custom configPath row. It matches configDir = resolve(configPath, '..') in cli-builder.ts.

@garretpremo garretpremo added first pass reviewed Review passed with no blocking issues and removed changes requested Review found blocking issues labels Oct 19, 2026

@garretpremo garretpremo left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 Final review by claude — generated by the final-review skill. CI is green, no blockers, soak window elapsed. Marking approved and merging.

Approved.

@garretpremo garretpremo added approved PR has been fully approved and is ready to merge and removed first pass reviewed Review passed with no blocking issues labels Oct 19, 2026
@garretpremo
garretpremo merged commit bad93e0 into dev Oct 19, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

approved PR has been fully approved and is ready to merge

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant