Get Started

CLI reference

Install, authenticate, select workspaces, manage packs and tracks, and run Epismo in CI.

The epismo CLI is the best place to start with Epismo. It is also useful for day-to-day operations and CI jobs. CLI payloads closely match HTTP API request bodies, so examples that work locally are good starting points for product integrations.

Setup and authentication

Start with Setup to install the CLI and understand JSON input/output.

Then use Authentication to sign in, sign out, and understand local credential storage.

Workspace selection

Every CLI command runs in one execution context.

  1. If EPISMO_TOKEN is set, the token's embedded workspace is used.
  2. Otherwise the saved default from epismo workspace use <workspace-id> is used.
  3. If no workspace is selected, commands use personal space.
epismo workspace list
epismo workspace current
epismo workspace use <workspace-id>
epismo workspace clear

Use workspace clear when you want commands to operate on personal data again.

Create and read packs

Packs store reusable knowledge and process. workflow packs use steps; context packs use blocks.

epismo pack create --type context --title "Repo map" --personal \
  --blocks '[{"title":"Services","content":"api, mcp, cli"}]'
epismo pack create --type workflow --title "Release review" --projects <project-id> \
  --steps '[{"title":"Summarize changes","content":"List merged PRs."},{"title":"Check migrations","content":"Confirm database impact."}]'

By default, pack get returns outline data. Use --full for all nested content or --block-id / --step-id for selected content.

epismo pack get <pack-id>
epismo pack get <pack-id> --full
epismo pack get @repo-map --block-id b001,b002
epismo pack get @handle/repo-map
epismo pack get https://epismo.ai/share/<token>

Update packs

Pack updates use PATCH semantics. Omitted fields stay unchanged. Nested content is updated with operation arrays.

epismo pack update @repo-map --blocks '[{"op":"add","title":"Local setup","content":"npm install"}]'
epismo pack update @repo-map --blocks '[{"op":"update","id":"b001","content":"Updated text"}]'
epismo pack update @repo-map --blocks '[{"op":"remove","id":"b002"}]'

Workflow steps use the same pattern through steps.

Create and search tracks

Tracks represent active work.

epismo track create --type task --title "Fix API docs" --personal \
  --task '{"status":"todo","dueDate":"2026-06-05"}'
 
epismo track create --type goal --title "Ship docs v1" --projects <project-id> \
  --goal '{"status":"on_track","progress":40}'

Task statuses are backlog, todo, in_progress, and done. Goal statuses are not_started, on_track, at_risk, postponed, and completed.

epismo track search --type task --personal --filter '{"status":["todo","in_progress"]}'
epismo track search --type goal --projects <project-id> --filter '{"progressMin":50}'

Use track apply when planning multiple tasks at once.

epismo track apply --personal --input '{
  "updateDrafts": [
    {"id":"t001","title":"Task A","task":{"status":"todo"}},
    {"id":"t002","title":"Task B","task":{"status":"todo","dependsOn":["t001"]}}
  ]
}'

Non-UUID IDs such as t001 and t002 create new records and can be referenced by other drafts in the same request.

Aliases

Aliases are human-readable references to packs.

epismo alias upsert @deploy-review --type workflow --id <pack-id>
epismo alias get @deploy-review
epismo alias get @handle/deploy-review
epismo alias list --type workflow
epismo alias delete @deploy-review

Alias names are stored without the leading @. They cannot contain / or control characters. Owner prefixes are used only when reading aliases owned by someone else.

Workspace and project management

Workspaces are organization boundaries. Projects are private sharing containers.

epismo workspace create --name "Team" --plan basic
epismo workspace update <workspace-id> --name "New name"
epismo workspace checkout <workspace-id>
 
epismo workspace member list
epismo workspace member upsert <user-id> --role admin
epismo workspace member delete <user-id>
epismo project list
epismo project create --name "Website" --description "Docs and marketing site"
epismo project update <project-id> --name "Website docs"
epismo project member add <user-id> --project-id <project-id>

Agents and credits

Installed agents can be assigned to tasks and workflow steps.

epismo agent list
epismo agent add --agent-ids agent_a,agent_b
epismo agent remove --agent-ids '["agent_a","agent_b"]'

Use credit commands for balance and checkout.

epismo credit balance
epismo credit checkout --allocations '[{"userId":"<user-id>","quantity":500}]'

Credits are consumed by agent usage, pack search, track search, and pack reads. In the CLI, this includes epismo pack search, epismo track search, and epismo pack get in outline, selected block/step, or full mode. For large packs, inspect the outline first and then fetch only the blocks or steps needed.

CI/CD tokens

Use CLI tokens in CI instead of OTP login.

epismo token create --workspace-id <workspace-id>

Store the token as a CI secret and pass it as EPISMO_TOKEN.

export EPISMO_TOKEN="$EPISMO_TOKEN"
epismo pack search --type context --query "release"
epismo track apply --input @plan.json

When EPISMO_TOKEN is set, saved workspace defaults are ignored. This keeps CI execution context stable.

Command cheat sheet

Use All commands for a compact command index.

In this section