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 "Team onboarding" --personal \
  --blocks '[{"title":"Where things live","content":"Docs in Notion, code in GitHub, designs in Figma."}]'
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/$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 '{
  "upserts": [
    {"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 upserts in the same request.

Aliases

Aliases are human-readable references to packs.

epismo alias upsert @deploy-review --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 upsert $USER_ID_1,$USER_ID_2 --role member
epismo workspace member delete $USER_ID
epismo workspace member delete $USER_ID_1,$USER_ID_2
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
epismo project member add $USER_ID_1,$USER_ID_2 --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}]'

CLI credit costs are listed by command in Credits. For large packs, inspect the outline first and then fetch only the blocks or steps needed.

Command cheat sheet

Use All commands for a compact command index.

In this section