CLI Reference
The public jejoo-cli package provides analyze and local. Use jejoo --version to check the installed release, and jejoo COMMAND --help for its options. Server development and evaluation commands belong to the full repository distribution.
Analyze
jejoo analyze traces.jsonl \
--api-base-url https://app.scaillabs.ai \
--output-dir .jejoo/my-analysis
For a connector, omit the file and supply --source langsmith or --source langfuse. Every analysis requires an API URL and output directory. A fresh directory starts a new analysis; the original directory resumes saved work when inputs match.
Common options
Use --workflow repeatedly for source context, --objective to specify your goal, and --wait-timeout-seconds to extend the wait. Full workflow contents are sent to the service. See Input Formats and Privacy & Data Handling.
| Argument | Default | Description |
|---|---|---|
input | Required with --source file | Raw trace file to normalize locally. |
--source | file | Trace input source; file, langsmith, or langfuse. |
--source-project | — | LangSmith project name (required), or Langfuse credentials' project name to verify. |
--since | 7d for connectors | Root start bound: duration (e.g. 7d) or ISO time; default 7d. |
--until | Now for connectors | Exclusive root start bound; default now. |
--max-traces | 100 for connectors | Root retrieval cap; default 100. |
--tag | — | Required root tag; repeat for all tags. |
--name | — | Exact root entry-point name. |
--trace-id | — | Trace ID; repeat to select several. |
--source-filter | — | Advanced root filter: LangSmith expression or Langfuse JSON condition array. |
--tree-filter | — | LangSmith only: select traces containing a matching internal run. |
--workflow | — | Optional workflow source file; repeat for multiple files (10 files, 200000 bytes total). Contents are sent to the server. Omit to derive an observed workflow locally from trace facts. |
--workflow-normalization | llm | Server-side LLM normalization (default), or canonical DeclaredWorkflow JSON passthrough. |
--project-id | JEJOO_PROJECT_ID, or anonymous project | Project for API-key authentication (default: JEJOO_PROJECT_ID; OPTIMAIZE_PROJECT_ID is also accepted). |
--output-dir | Required | Local artifacts and resume state; use a fresh directory for new inputs. |
--redaction-policy-id | cli-default-v1 | Policy label; does not itself remove any fields. |
--objective | Optimize the observed workflow. | Goal for the analysis. |
--mapping | — | Optional operation-name to node-id JSON mapping. |
--request-id | — | Explicit normalization request identity; normally generated. |
--submission-id | — | Explicit analysis submission identity; normally generated. |
--remove-key | — | Remove a matching field name recursively from normalization samples; repeatable. |
--hash-key | — | Hash matching sample fields with SHA-256; repeatable. |
--hash-salt-env | — | Environment variable containing the private hash salt. |
--profile-record-limit | 500 | Maximum source records used for the local profile. |
--sample-size | 20 | Representative normalization samples; cannot exceed the profile limit. |
--max-source-bytes | 1073741824 | Maximum trace file or connector export bytes (default 1 GiB). |
--max-execution-facts | 5000000 | Maximum locally normalized execution facts. |
--max-distinct-runs | 10000 | Maximum distinct run identities. |
--max-canonical-bytes | 2147483648 | Maximum canonical storage bytes (default 2 GiB). |
--allow-column | — | Narrow the built-in outbound evidence allowlist; repeatable. |
--block-column | — | Exclude an outbound evidence column; repeatable. |
--max-rows | 100 | Maximum rows per evidence request; service limits can be lower. |
--max-requests | 8 | Maximum evidence requests handled by the continuation. |
--max-total-rows | 1000 | Total evidence-row budget across continuation. |
--max-total-bytes | 1048576 | Total evidence-response byte budget (default 1 MiB). |
--poll-interval-seconds | 2.0 | Seconds between analysis polls. |
--wait-timeout-seconds | 600.0 | Seconds to wait for analysis completion. |
--api-base-url | Required | Jejoo service URL, usually https://app.scaillabs.ai. |
--api-token-env | JEJOO_API_KEY | Environment variable containing a provisioned Jejoo API key. |
--timeout-seconds | 180.0 | Transport timeout in seconds. |
Trace selection
Selection flags apply only to connectors. --since is inclusive and --until exclusive; they apply to root start times. The default window is the previous seven days, with at most 100 roots. Explicit trace IDs still respect the time window and other filters. Repeated tags require all tags. The cap follows provider retrieval order and is not representative sampling.
--source-project means a provider project, distinct from Jejoo's --project-id. LangSmith requires it; Langfuse credentials select the project and the optional name verifies it. --tree-filter is LangSmith-only. See connector setup.
Authentication and configuration
Anonymous use needs no account or API key. To use a provisioned project, set JEJOO_API_KEY and JEJOO_PROJECT_ID in your private environment, then run the same command. --api-token-env changes which environment variable supplies the token; never pass the actual token as the flag value. --project-id overrides the environment's project ID.
JEJOO_CONFIG_DIR overrides the default ~/.config/jejoo credential directory. Legacy OPTIMAIZE_* environment names remain accepted; a corresponding JEJOO_* value takes precedence, including an empty value. The optimaize and optimaize-analyze commands remain aliases. jejoo-analyze directly invokes analyze.
Limits and allowance
Local limits restrict input size, fact count, and evidence exchange. --sample-size cannot exceed --profile-record-limit. --max-rows must be at most 1,000; the anonymous service further limits each request to 100 rows and each analysis to eight evidence requests. Anonymous JSON requests are limited to 1 MiB. Local flags do not override server limits.
Anonymous analysis has rolling usage allowances and concurrency limits. Admission checks current allowance before new normalization work, but does not reserve the cost of a complete analysis. Further model calls can still exhaust allowance mid-run. Changing output directories does not reset the allowance.
Local stages
analyze handles the usual end-to-end flow. These commands expose individual stages for inspection and recovery:
| Command | Purpose |
|---|---|
jejoo local prepare | Write a redacted normalization request and private local state. |
jejoo local request | Ask the service for a normalization envelope. |
jejoo local apply | Apply the envelope locally with a canonical workflow. |
jejoo local start-request | Write the registration payload for inspection. |
jejoo local start | Register a saved submission and local fact revision. |
jejoo local status | Read job status and optionally download its result. |
jejoo local evidence | Answer one server-issued evidence request locally. |
jejoo local continue | Process evidence rounds and save completed results. |
Run jejoo local COMMAND --help for required arguments. For example:
jejoo local status YOUR_JOB_ID \
--api-base-url https://app.scaillabs.ai \
--result-output .jejoo/my-analysis/status.json
This status command reads the job; use the original analyze command to resume the evidence exchange and report generation.
Recovery and troubleshooting
| Symptom | Next step |
|---|---|
| Timeout or interrupted connection | Rerun the same command/output directory. Increase --wait-timeout-seconds for a longer analysis. |
| Inputs or objective changed | Use a fresh output directory. Saved work is tied to the original inputs. |
| Saved facts have no job receipt | Inspect submission.json; use local start --help to register the saved submission and manifest. Check whether the previous submission reached the service first: analysis submission is not automatically repeated. |
| Waiting for evidence | Keep analyze running or resume the original command with the matching local facts. |
| Usage allowance reached / rate limit | Wait for allowance recovery or use a provisioned project. A failed job requires a fresh analysis after allowance is available. |
| Expired anonymous job credential | Start a new analysis; anonymous job credentials expire with the job. |
| Source export already exists | Use a fresh directory for a new connector export. |
| Invalid canonical workflow | Use default llm normalization for arbitrary JSON; canonical mode requires schema-valid DeclaredWorkflow. |
| Certificate verification failed | Update the CLI. Configure SSL_CERT_FILE or SSL_CERT_DIR if your organization requires custom trusted roots. |
--timeout-seconds controls transport requests; --wait-timeout-seconds controls waiting for analysis completion. Increasing one does not increase the other. HTTPS certificate and hostname verification stay enabled.